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Production Note 


This book was produced with the VAX DOCUMENT electronic publishing 
system, a software tool developed and sold by Digital. In this system, 
writers use an ASCII text editor to create source files containing text and 
English-like code; this code labels the structural elements of the document, 
such as chapters, paragraphs, and tables. The VAX DOCUMENT software, 
which runs on the VMS operating system, interprets the code to format 
the text, generate a table of contents and index, and paginate the entire 
document. Writers can print the document on the terminal or line printer, 
or they can use Digital-supported devices, such as the LNO3 laser printer 
and PostScript printers (PrintServer 40 or LNO3R ScriptPrinter), to 
produce a typeset-quality copy containing integrated graphics. 
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Intended Audience 


This manual is intended for system programmers who want to take 
advantage of the time and space savings that result from direct use of I/O 
devices. Users of VMS who do not require such detailed knowledge of I/O 
drivers can use the device-independent services described in the 

VMS Record Management Services Manual. 





Document Structure 


This manual is organized into eleven chapters and three appendixes, as 
follows: 


Chapter 1 describes the Queue I/O (QIO) interface to file system 
ancillary control processes (ACPs). 


Chapters 2 through 11 describe the use of VMS file-structured and 
real-time J/O device drivers, the drivers for storage devices such as 
disks and magnetic tapes, and terminal devices supported by VMS: 


— Chapter 2 discusses the card reader driver. 

— Chapter 3 discusses disk drivers. 

— Chapter 4 discusses the LPA11-K driver. 

— Chapter 5 discusses the line printer drivers. 

— Chapter 6 discusses the magnetic tape drivers. 

— Chapter 7 discusses the mailbox driver. 

— Chapter 8 discusses the terminal driver. 

— Chapter 9 discusses the pseudoterminal driver. 

— Chapter 10 discusses the shadow-set virtual unit driver. 


— Chapter 11 discusses the VMS Generic Small Computer Systems 
Interface (SCSI) class driver. 


Appendix A summarizes the QIO function codes, arguments, and 
function modifiers used by the drivers listed above. 


Appendix B lists the DEC Multinational Character Set and the ANSI 
and DIGITAL-private escape sequences for terminals. 


Appendix C describes the VAX calling standards for the control 
connection routines. 
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Associated Documents 


The following documents provide additional information: 


¢ VMS System Services Reference Manual 

¢ VMS Software Information Management Handbook 
¢ VMS Software VMS System Software Handbook 

¢ Guide to VMS Programming Resources 


¢ VMS Record Management Services Manual 

e LPA11-K Laboratory Peripheral Accelerator User’s Guide 

e VMS Networking Manual 

¢ VMS System Messages and Recovery Procedures Reference Manual 


¢ VMS Device Support Manual 





Conventions 


The following conventions are used in this manual: 


Ciri/x 


PF1 x 


XXiv 


A sequence such as Cirl/x indicates that you must 
hold down the key labeled Ctrl while you press 
another key or a pointing device button. 


A sequence such as PF1 x indicates that you must 
first press and release the key labeled PF1, then 
press and release another key or a pointing device 
button. 


In examples, a key name is shown enclosed in a box 
to indicate that you press a key on the keyboard. (In 
text, a key name is not enclosed in a box.) 


In examples, a horizontal ellipsis indicates one of the 
following possibilities: 


* Additional optional arguments in a statement 
have been omitted. 

* The preceding item or items can be repeated one 
or more times. 

¢ Additional parameters, values, or other 
information can be entered. 


A vertical ellipsis indicates the omission of items from 
a code example or command format; the items are 
omitted because they are not important to the topic 
being discussed. 


In format descriptions, parentheses indicate that, if 
you choose more than one option, you must enclose 
the choices in parentheses. 


red ink 


boldface text 


italic text 


UPPERCASE TEXT 


numbers 
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In format descriptions, brackets indicate that whatever 
is enclosed within the brackets is optional; you can 
select none, one, or all of the choices. (Brackets are 
not, however, optional in the syntax of a directory 
name in a file specification or in the syntax of a 
substring specification in an assignment statement.) 


In format descriptions, braces surround a required 
choice of options; you must choose one of the options 
listed. 


Red ink indicates information that you must enter from 
the keyboard or a screen object that you must choose 
or click on. 


For online versions of the book, user input is shown in 
bold. 


Boldface text represents the introduction of a new 
term or the name of an argument, an attribute, or a 
reason. 


Boldface text is also used to show user input in online 
versions of the book. 


Italic text represents information that can vary 
in system messages (for example, Internal error 
number). 


Uppercase letters indicate that you must enter a 
command (for example, enter OPEN/READ), or they 
indicate the name of a routine, the name of a file, the 
name of a file protection code, or the abbreviation for 
a system privilege. 


Hyphens in coding examples indicate that additional 
arguments to the request are provided on the line that 
follows. 


Unless otherwise noted, all numbers in the text are 
assumed to be decimal. Nondecimal radixes—binary, 
octal, or hexadecimal—are explicitly indicated. 
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ACP—QIO Interface 


An ancillary control process (ACP) is a process that interfaces between the 
user process and the driver, and performs functions that supplement the 
driver’s functions. Virtual I/O operations involving file-structured devices 
(disks and magnetic tapes) often require ACP intervention. In most cases, 
ACP intervention is requested by VMS Record Management Services 
(RMS) and is transparent to the user process. However, user processes can 
request ACP functions directly by issuing a QIO request and specifying an 
ACP function code, as shown in Figure 1-1. 


Executing physical and logical I/O operations on a device being managed 
by a file ACP will interfere with the operation of the ACP and will result 
in unpredictable consequences, including system failure in certain cases. 


In addition to the ACP, the VMS operating system also provides the XQP 
(extended QIO processor) facility to supplement the QIO driver’s functions 
when performing virtual I/O operations on file-structured devices (ACP 
for Files—11 On-Disk Structure Level 1 and XQP for Files—11 On-Disk 
Structure Level 2). However, rather than being a separate process, the 
XQP executes as a kernel mode thread in the process of its caller. 


This chapter describes the QIO interface to ACPs for disk and magnetic 
tape devices (file system ACPs). The sample program in Chapter 6 
performs QJO operations to the magnetic tape ACP. 


Figure 1-1 ACP-—QIO Interface 


Process ACP 
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This section also describes a number of structures and field names of the 
form xxx$name. A VAX MACRO program can define symbols of this form 
by invoking the $xxxDEF macro. 


The following macros are available in SYS$LIBRARY:STARLET.MLB: 


$IODEF 

$FIBDEF 
$ATRDEF 
$SBKDEF 
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The following macros are available in SYS$LIBRARY:LIB.MLB: 


$FATDEF 
$DQFDEF 
$FCHDEF 


Programs written in BLISS-32 can use these symbols by referencing 
them and including the correct library, SYS$LIBRARY:STARLET.L32 
(for the macros listed under SYS$LIBRARY:STARLET.MLB), 

and SYS$LIBRARY:LIB.L32 (for the macros listed under 
SYS$LIBRARY:LIB.MLB). 


References to ANSI refer to the American National Standard Magnetic 
Tape Labels and File Structures for Information Interchange, ANSI 
X3.27-1978. 


1.1 ACP Functions and Encoding 


All VMS ACP functions can be expressed using seven function codes and 
four function modifiers. The function codes are as follows: 


¢ I0$_CREATE—Creates a directory entry or file 


¢ JIO$_ACCESS—Searches a directory for a specified file and accesses 
the file, if found 


¢ J0$_DEACCESS—Deaccesses a file and, if specified, writes the final 
attributes in the file header 


¢ I0$ MODIFY—Modifies the file attributes and file allocation 
¢ 10$ _DELETE—Deletes a directory entry and file header 


¢ I0$ MOUNT —Informs the ACP when a volume is mounted; requires 
MOUNT privilege 


¢ I0$ ACPCONTROL—Performs miscellaneous control functions 


The function modifiers are: 

¢ IO$M_ACCESS—Opens a file on the user’s channel 

¢ JIO$M_CREATE—Creates a file 

¢ JO$M_DELETE—Deletes a file (or marks it for deletion) 
¢ JO$M_DMOUNT—Dismounts a volume 


In addition to the function codes and modifiers, VMS ACPs take five 
device- or function-dependent arguments, as shown in Figure 1-2. The 
first argument, P1, is the address of the file information block (FIB) 
descriptor. Section 1.2 describes the FIB in detail. 


The second argument, P2, is an optional argument used in directory 
operations. It specifies the address of the descriptor for the file name 
string to be entered in the directory. 


ACP—AQIO Interface 
1.1 ACP Functions and Encoding 


Argument P3 is the address of a word to receive the resultant file name 
string length. The resultant string is not padded. The actual length is 
returned in P3. P4 is the address of a descriptor for a buffer to receive the 
resultant file name string. Both of these arguments are optional. 


Figure 1-2 ACP Device- or Function-Dependent Arguments 


31 












Pt: Address of FIB Descriptor 


0 
Address of File Name String Descriptor (Optional) 
Address of Word to Receive Resultant String Length (Optional) 
é‘ ional) 

ional) 


P2: 
P3: 
P4: 


Address of Resultant String Descriptor (Optional 
Address of Attribute Contro! Block (Optional 
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P5: 


The fifth argument, P5, is an optional argument containing the address 
of the attribute control block. Section 1.3.5 describes the attribute control 
block in detail. 


All areas of memory specified by the descriptors must be capable of being 
read or written to. 


Figure 1-3 shows the format for the descriptors. The count field is the 
length in bytes of the item described. 


Figure 1-3 ACP Device/Function Argument Descriptor Format 


31 16 15 0 
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1.2 File Information Block (FIB) 


The file information block (FIB) contains much of the information that is 
exchanged between the user process and the ACP. Figure 1—4 shows the 
format of the FIB. The FIB must be writable. Because the FIB is passed 
by a descriptor (see Figure 1-3), its length can vary. Thus, a short FIB can 
be used in ACP calls that do not need arguments near the end of the FIB. 
The ACP treats the omitted portion of the FIB as if it were 0. Figure 1-5 
shows the format of a typical short FIB that would be used to open an 
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existing file. Table 1-1 gives a brief description of each of the FIB fields. 
More detailed descriptions are provided in Sections 1.3 and 1.6. 


Figure 1-4 File Information Block Format 


31 24 23 16 15 


87 0 
FIB$B_WSIZE FIB$L_ACCTL 


FIB$W_FID 















FIBSW_DID 


FIB$B_ALALIGN | FIB$B_ALOPTS 












FIB$W_ALLOC 
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Figure 1-5 Typical Short File Information Block 


31 24 23 
FIB$B_WSIZE 








FIB$W_DID 


FIB$L_WCC 
FIBS\W_NMCTL 


+ 0 


16 15 87 0 











FIB$L_ACCTL 





FIB$W_FID 











+ 0 
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Table 1-1 Contents of the File Information Block 


Field Subfields 
FIB$L_ACCTL 


FIB$B_WSIZE 


FIB$W_FID 


FIBSW_FID_NUM 

FIBSW_FID_SEQ 

FIB$W_FID_RVN 

FIB$B_FID_RVN 

FIB$B_FID_NMX 
FIB$W_DID 


FIB$W_DID_NUM 
FIBSW_DID_SEQ 
FIB$W_DID_RVN 


Meaning 


Contains flag bits that control the access to the file. Sections 
1.3.1.1, 1.3.2.1, 1.6.1.1, 1.6.4.1, and 1.6.5 describe the 
FIB$L_ACCTL field flag bits. 


Controls the size of the file window used to map a disk file. If a 
window size of 255 is specified, the file is mapped completely 
through the use of segmented windows. 


Specifies the file identification. You supply the file identifier 
when it is known; the ACP returns the file identifier when 

it becomes known, for example, as a result of a create or 
directory lookup. A 0 file identifier can be specified when an 
operation is performed on a file that is already open on a 
particular channel. The ACP returns the file identifier of the 
open file. The following subfields are defined: 


File number. 

File sequence number. 

Relative volume number (only for magnetic tape devices). 
Relative volume number (only for disk devices). 

File number extension (only for disk devices). 


Contains the file identifier of the directory file. The following 
subfields are defined: 


File number. 
File sequence number. 
Relative volume number (only for magnetic tape devices). 





(continued on next page) 
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Table 1-1 (Cont.) Contents of the File Information Block 





Field Subfields Meaning 
FIB$B_DID_RVN Relative volume number (only for disk devices). 
FIB$B_DID_NMX File number extension (only for disk devices). 
FIB$L_WCC Maintains position context when processing wildcard directory 
operations. 
FIB6W_NMCTL Contains flag bits that control the processing of a name string 


in a directory operation. Sections 1.3.1.1 and 1.6.1.1 describe 
the FIBSW_NMCTL field flag bits. 


FIBSW_EXCTL Contains flag bits that specify extend control for disk devices. 
Sections 1.3.3.1 and 1.3.4.1 describe the FIB$W_EXCTL field 
flag bits. 

FIB$W_CNTRLFUNC In an 1O$_ACPCONTROL function, this field contains the code 


that specifies which ACP control function is to be performed 
(see Section 1.6.7). This field overlays FIB6W_EXCTL. 


FIB$C_USEREOT User EOT mode. In an IO$_CREATE or |O$_ACCESS 
function, you can set this mode on a per-file basis. (See 
Sections 1.6.1 and 1.6.2.) 


FIB$L_EXSZ Specifies the number of blocks to be allocated in an extend 
operation on a disk file. 
FIB$L_CNTRLVAL Contains a control function value used in an lO$_ 


ACPCONTROL function (see Section 1.6.7). The interpretation 
of the value depends on the control function specified in 
FIB$W_CNTRLFUNC. This field overlays FIB$L_EXSZ. 


FIB$L_EXVBN Specifies the starting disk file virtual block number at which a 
file is to be truncated. 


FIB$B_ALOPTS Contains option bits that control the placement of allocated 
blocks. Section 1.3.3.1 describes the FIB$B_ALOPTS field flag 
bits. 

FIB$B_ALALIGN Contains the interpretation mode of the allocation 
(FIBSW_ALLOC) field. 

FIB$W_ALLOC Contains the desired physical location of the blocks being 


allocated. Interpretation of the field is controlled by the 
FIB$B_ALALIGN field. The following subfields are defined: 


FIB$W_LOC_FID Three-word related file ID for RF! placement. 

FIB$W_LOC_NUM Related file number. 

FIB$}W_LOC_SEQ Related file sequence number. 

FIB$B_LOC_RVN Related file RVN or placement RVN. 

FIB$B_LOC_NMX Related file number extension. 

FIB$L_LOC_ADDR Placement LBN, cylinder, or VBN. 
FIBSW_VERLIMIT Contains the version limit of the directory entry. 
FIB$L_ACLCTX Maintains position context when processing ACL attributes 


from the attribute (P5) list. 
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Table 1-1 (Cont.) Contents of the File Information Block 
Field Subfields Meaning 


FIB$L_ACL_STATUS Status of the requested ACL attribute operation, if any. The 
ACL attributes are included in Table 1-7. If no ACL attributes 
are given, SS$_NORMAL is returned here. 


FIB$L_STATUS Access status. Applies to all major functions. The following 
bits are supported: 


FIB$V_ALT_ REQ Set to indicate whether the alternate access bit is required for 
the current operation. If not set, the alternate access bit is 
optional. 

FIB$V_ALT_GRANTED _ If FIB$V_ALT_REQ = 0, the FIB bit returned from the file 
system is set if the alternate access check succeeded. 

FIB$L_ALT_ACCESS A 32-bit mask that represents an access mask to check against 
file protection; for example, opens a file for read access and 


checks whether it can be deleted. The mask has the same 
configuration as the standard protection mask. 





1.3 ACP Subfunctions 


The operations that the ACP performs can be organized into two 
categories: major ACP functions and subfunctions. Each ACP operation 
performs one major function. That function is specified by an I/O function 
code, such as IO$_ACCESS, IO$_CREATE, or I0$_ MODIFY. While 
executing the major function, one or more subfunctions can be performed. 
A subfunction is an operation such as looking up, accessing, or extending 
a file. Most subfunctions can be executed by more than one of the major 
functions. Sections 1.3.1 through 1.3.5 describe the following subfunctions 
in detail: 


¢ Directory Lookup 


e Access 
e Extend 
¢ Truncate 


e¢ Read Attributes 
e Write Attributes 


Section 1.6, which contains the descriptions of the major functions, lists 
the subfunctions available to each major function. 


1.3.1. Directory Lookup 


The directory lookup subfunction is used to search for a file in a disk 
directory or on a magnetic tape. This subfunction can be invoked using 
the major functions IO$_ACCESS, I0$_MODIFY, I0$_DELETE, and 
I0$_ACPCONTROL. A directory lookup occurs if the directory file ID field 
in the FIB (FIB$W_DID) is a nonzero number. 
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1.3.1.1 Input Parameters 


Table 1-2 lists the FIB fields that control the processing of a lookup 


subfunction. 


Table 1-2 FIB Fields (Lookup Control) 





Field Field Values Meaning 
FIB$W_NMCTL Name string control. The following name control bits are 
applicable to a lookup operation: 
FIB$M_WILD Set if name string contains wildcards. Setting this bit causes 


FIB$M_ALLNAM 
FIB$M_ALLTYP 
FIB$M_ALLVER 


FIB$M_FINDFID 
FIB$W_FID 
FIB$W_DID 
FIB$L_WCC 
FIB$L_ACCTL 
FIB$M_REWIND 


wildcard context to be returned in FIB$L_WCC. 

Set to match all name field values. 

Set to match all field type values. 

Set to match all version field values. 

Set to search a directory for the file identifier in FIB$W_FID. 


File identification. The file ID of the file found is returned in this 
field. 


Contains the file identifier of the directory file. This field must be a 
nonzero number. 


Maintains position context when processing wildcard directory 
operations. 


The following access control flag is applicable to a lookup 
subfunction: 


Set to rewind magnetic tape before lookup. If not set, a magnetic 
tape is searched from its current position. 


QIO arguments P2 through P6 are passed as values. The second 
argument, P2, specifies the address of the descriptor for the file name 
string to be searched for in the directory. 


The file name string must have one of the following two formats: 


name.type;version 


name.type.version 


The name and type can be any combination of alphanumeric characters, 
and the dollar sign ($), asterisk (*), and percent (%) characters. The 
version must consist of numeric characters optionally preceded by a minus 
sign (—) (only for disk devices) or a single asterisk. The total number of 
alphanumeric and percent characters in the name field and in the type 
field must not exceed 39. Any number of additional asterisks can be 


present. 


If any of the bits FIB$}M_ALLNAM, FIB$M_ALLTYP, and FIB$M_ 
ALLVER are set, then the contents of the corresponding field in the 
name string are ignored and the contents are assumed to be an asterisk. 


Note that the file name string cannot contain a directory string. The 
directory is specified by the FIB$W_DID field (see Table 1-1). Only VMS 
RMS can process directory strings. 
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Argument P83 is the address of a word to receive the resultant file name 
string length. 


Argument P4 is the address of a descriptor for a buffer to receive the 
resultant file name string. The resultant string is not padded. The P3 and 
P4 arguments are optional. 


1.3.1.2 Operation 
The system searches either the directory file specified by FIB$W_DID 
or the magnetic tape for the file name specified in the P2 file name 
parameter. The actual file name found and its length are returned in the 
P3 and P4 length and result string buffers. The file ID of the file found is 
returned in FIB$W_FID and can be used in subsequent operations as the 
major function is processed. 


Zero and negative version numbers have special significance in a disk 
lookup operation. Specifying 0 as a version number causes the latest 
version of the file to be found. Specifying —1 locates the second most recent 
version, —2 the third most recent, and so forth. Specifying a version of —0 
locates the lowest numbered version of the file. For magnetic tape lookups, 
a version number of 0 locates the first occurrence of the file encountered; 
negative version numbers are not allowed. 


Wildcard lookups are performed by specifying the appropriate wildcard 
characters in the name string and setting FIB$M_WILD. (The name 
control bits FIB$M_ALLNAM, FIB$M_ALLTYP, and FIB$M_ALLVER 
can also be used in searching for wildcard entries, but they are intended 
primarily for compatibility mode use.) On the first lookup, FIB$L_WCC 
should contain zero entries. On each lookup, the ACP returns a nonzero 
value in 

FIB$L_WCC, which must be passed back on the next lookup call. In 
addition, you must pass the resultant name string returned by the 
previous lookup using the P4 result string buffer, and its length in the 
P3 result length word. This string is used together with FIB$L_WCC to 
continue the wildcard search at the correct position in the directory. 


Perform a lookup by file ID by setting the name control bit FIB$M_ 
FINDFID. When this bit is set, the system searches the directory for an 
entry containing the file ID specified in FIB$W_FID, and the name of the 
entry found is returned in the P3 and P4 result parameters. Note that if 
a directory contains multiple entries with the same file ID, only the first 
entry can be located with this technique. 


Lookups by file ID should be done only when the file name is not available, 
because lookups by this method are often significantly slower than lookups 
by file name. 


1.3.1.3 Directory Entry Protection 
A directory entry is protected with the same protection code as the file 
itself. For example, if a file is protected against delete access, then the 
file name has the same protection. Consequently, a nonprivileged user 
(that is, a user who is not the volume owner or a user who does not have 
SYSPRV) cannot rename a file because renaming a file is essentially the 
same as deleting the file name. This protection is applied regardless of the 
protection on the directory file. 
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Nonprivileged users can neither write directly into a .DIR;1 directory file 
nor turn off the directory bit in a directory file header. 


Access 


The access subfunction is used to open a file so that virtual read or write 
operations can be performed. This subfunction can be invoked using the 
major functions IO$_CREATE and IO$_ACCESS (see Sections 1.6.1 and 
1.6.2). An access subfunction is performed if the IO$M_ACCESS modifier 
is specified in the I/O function code. 


1.3.2.1. Input Parameters 


Table 1-3 lists the FIB fields that control the processing of an access 


subfunction. 


Table 1-3 FIB Fields (Access Control) 


Field Field Values 
FIB$L_ACCTL 


FIB$M_WRITE 
FIB$M_NOREAD 


FIB$M_NOWRITE 
FIB$M_NOTRUNC 


FIB$M_DLOCK 


FIB$M_UPDATE 
FIB$M_READCK 
FIB$M_WRITECK 


FIB$M_EXECUTE 
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Meaning 


Specifies field values that control access to the file. The following 
access control bits are applicable to the access subfunction: 


Set for write access; clear for read-only access. 


Set to deny read access to others. (You must have write privilege 
to the file to use this option.) 


Set to deny write access to others. 


Set to prevent the file from being truncated; clear to allow 
truncation. 


Set to enable deaccess lock (close check). Used only for disk 
devices. 


Used to flag a file as inconsistent if the program currently 
modifying the file terminates abnormally. if the program 
deaccesses the file without performing a write attributes operation, 
the file is marked as locked and cannot be accessed until it is 
unlocked. 


Set to position at start of a magnetic tape file when opening file 
for write; clear to position at end-of-file. 

Set to enable read checking of the file. Virtual reads to the file 
are performed using a data check operation. 

Set to enable write checking of the file. Virtual writes to the file 
are performed using a data check operation. 


Set to access the file in execute mode. The protection check is 
made against the EXECUTE bit instead of the READ bit. Valid 
only for requests issued from SUPERVISOR, EXEC, or KERNEL 
mode. 


(continued on next page) 
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Table 1-3 (Cont.) FIB Fields (Access Control) 


Field 


FIB$B_WSIZE 


FIB$W_FID 


Field Values 


FIBSM_NOLOCK 


FIBSM_ 
NORECORD 


1.3.2.2 Operation 
The file is opened according to the access control specified (see Table 1-3). 


Extend 


1.3.3.1 


Table 1-4 FIB Fields (Extend Control) 


Field 
FIB$W_EXCTL 


Meaning 


Set to override exclusive access to the file, allowing you to access 
the file when another user has the file open with FIBS{M_NOREAD 
specified. You must have SYSPRV privilege or ownership of the 
volume to use this option. FIBSM_NOREAD and 
FIBM_NOWRITE must be clear for this option to work. 


Set to inhibit recording of the file’s expiration date. If not set, 
the file’s expiration date can be modified, depending on the file 
retention parameters of the volume. 


Controls the size of the file window used to map a disk file. The 
ACP uses the volume default if FIB$B_WSIZE is 0. A value of 1 
to 127 indicates the number of retrieval pointers to be allocated to 
the window. A value of —1 indicates that the window should be as 
large as necessary to map the entire file. Note that the window is 
charged to the user’s BYTELIM quota. 


Specifies the file identification of the file to be accessed. 


The extend subfunction is used to allocate space to a disk file. This 
subfunction can be invoked using the major I/O functions IO$_CREATE 
and IO$ MODIFY (see Sections 1.6.1 and 1.6.4). The extend subfunction 
is performed if the bit FIB$M_EXTEND is set in the extend control word 


FIB$W_EXCTL. 


Input Parameters 


Table 1—4 lists the FIB fields that control the processing of an extend 


subfunction. 


Field Values 


FIB$M_EXTEND 
FIBSM_NOHDREXT 
FIBSM_ALCON 


FIB$M_ALCONB 


Meaning 

Extend control flags. The following flags are applicable to the 
extend subfunction: 

Set to enable extension. 

Set to inhibit generation of extension file headers. 


Allocates contiguous space. The extend operation fails if the 
necessary contiguous space is not available. 


Allocates the maximum amount of contiguous space. 


(continued on next page) 
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Table 1-4 (Cont.) FIB Fields (Extend Control) 


Field Field Values 
FIB$M_FILCON 
FIB$M_ALDEF 

FIB$L_EXSZ 

FIB$L_EXVBN 


FIB$B_ALOPTS 


FIB$M_EXACT 


FIB$M_ONCYL 


FIB$B_ALALIGN 


(zero) 
FIB$C_CYL 
FIB$C_LBN 


FIB$C_VBN 


FIB$C_RFI 


FIBGW_ALLOC 


FIB$W_LOC_FID 
FIB$W_LOC_NUM 
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Meaning 


If both FIB$M_ALCON and FIB$M_ALCONB are set, a single 
contiguous area, whose size is the largest available but not 
greater than the size requested, is allocated. 


Marks the file contiguous. This bit can only be set if the file does 
not have space already allocated to it. 


Allocates the extend size (FIB$L_EXSZ) or the system default, 
whichever is greater. 


Specifies the number of blocks to allocate to the file. 


The number of blocks actually allocated for this operation is 
returned in this longword. More blocks than requested can be 
allocated to meet cluster boundaries. 


Returns the starting virtual block number of the blocks allocated. 
FIB$L_EXVBN must initially contain 0 blocks. 


Contains option bits that control the placement of allocated blocks. 
The following bits are defined: 


Set to require exact placement; clear to specify approximate 
placement. If this bit is set and the specified blocks are not 
available, the extend operation fails. 


Set to locate allocated space within a cylinder. This option 
functions correctly only when FIB$M_ALCON or FIB$M_ALCONB 
is specified. 

Contains the interpretation mode of the allocation 
(FIB$W_ALLOC) field. One of the following values can be 
specified: 

No placement data. The remainder of the allocation field is 
ignored. 


Location is specified as a byte relative volume number (RVN) in 
FIB$B_LOC_RVN and a cylinder number in FIB$L_LOC_ADDR. 


Location is specified as a byte RVN in FIB$B_LOC_RVN, followed 
by a longword logical block number (LBN) in FIBSL_LOC_ADDR. 


Location is specified as a longword virtual block number (VBN) 
of the file being extended in FIB$L_LOC_ADDR. A 0 VBN or one 
that fails to map indicates the end of the file. 


Location is specified as a three-word file ID in FIBSW_LOC_FID, 
followed by a longword VBN of that file in FIB$L_LOC_ADDR. A 
0 file ID indicates the file being extended. A 0 VBN or one that 
fails to map indicates the end of that file. 


Contains the desired physical location of the blocks being 
allocated. Interpretation of the field is controlled by the 
FIB$B_ALALIGN field. The following subfields are defined: 


Three-word related file ID for RFI placement. 
Related file number. 


(continued on next page) 
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Table 1—4 (Cont.) FIB Fields (Extend Control) 


Field 


Field Values Meaning 


FIBSW_LOC_SEQ Related file sequence number. 
FIB$B_LOC_RVN Related file RVN or placement RVN. 
FIB$B_LOC_NMX Related file number extension. 
FIB$L_LOC_ADDR Placement LBN, cylinder, or VBN. 


1.3.3.2 Operation 


Truncate 


1.3.4.1 


The specified number of blocks are allocated and appended to the file. 
The virtual block number assigned to the first block allocated is returned 
in FIB$L_EXVBN. The actual number of blocks allocated is returned in 
FIB$L_EXSZ. 


The actual number of blocks allocated is also returned in the second 
longword of the user’s I/O status block. If a contiguous allocation (FIB$M_ 
ALCON) fails, the size of the largest contiguous space available on the 
disk is returned in the second longword of the user’s I/O status block. 


The truncate subfunction is used to remove space from a disk file. This 
subfunction can be invoked by the major I/O functions IO$_DEACCESS 
and IO$_MODIFY (see Sections 1.6.3 and 1.6.4). The truncate subfunction 
is performed if the bit FIB$}M_TRUNCATE is set in the extend control 
word FIB$W_EXCTL. 


Input Parameters 


Table 1-5 lists the FIB fields that control the processing of a truncate 
subfunction. 


Table 1-5 FIB Fields (Truncate Control) 


Field 
FIB$W_EXCTL 


FIB$L_EXSZ 


Field Values Meaning 


Extend control flags. The following flags are applicable to the 
truncate subfunction: 


FIB$M_TRUNC Must be set to enable truncation. 
FIBSM_MARKBAD Set to append the truncated blocks to the bad block file, instead 


of returning them to the free storage pool. Only one cluster can 
be deallocated. This is most easily accomplished by specifying 
the last VBN of the file in FIB$L_EXVBN. SYSPRV privilege or 
ownership of the volume is required to deallocate blocks to the 
bad block file. . 

Returns the actual number of blocks deallocated. FIB$L_EXSZ 
must initially contain a value of 0. 


(continued on next page) 
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Table 1-5 (Cont.) FIB Fields (Truncate Control) 


Field 


FIB$L_EXVBN 


Field Values Meaning 


Specifies the first virtual block number to be removed from the file. 
The actual starting virtual block number of the truncate operation 
is returned in this field. 


1.3.4.2 Operation 


Blocks are deallocated from the file, starting with the virtual block 
specified in FIB$L_EXVBN and continuing through the end of the file. 
The actual number of blocks deallocated is returned in FIB$L_EXSZ. The 
virtual block number of the first block actually deallocated is returned in 
FIB$L_EXVBN. Because of cluster round-up, this value might be greater 
than the value specified. If FIB$M_MARKBAD is specified, the truncation 
VBN is rounded down instead of up, and the value returned in FIB$L_ 
EXVBN might be less than that specified. 


The number of blocks by which FIB$L_EXVBN was rounded up is 
returned in the second longword of the I/O status block. 


The truncate subfunction normally requires exclusive access to the file at 
run time. This means, for example, that a file cannot be truncated while 
multiple writers have access to it. 


An exception occurs when a truncate subfunction is requested for a write- 
accessed file that allows other readers. Although the truncate subfunction 
returns success status in this instance, the actual file truncation (the 
return of the truncated blocks to free storage) is deferred until the 

last reader deaccesses the file. If a new writer accesses the file after 

the truncate subfunction is requested, but before the last deaccess, the 
deferred truncation is ignored. 


1.3.5 Read/Write Attributes 


1.3.5.1 
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The read and write attributes subfunctions are used for operations such 
as reading and writing file protection and creating and revising dates. A 
read or write attributes operation is invoked by specifying an attribute list 
with the QIO parameter P5. A read attributes operation can be invoked by 
the major I/O function IO$_ACCESS (see Section 1.6.2); a write attributes 
operation can be invoked by the major I/O functions I0$_CREATE, IO$_ 
DEACCESS, and IO$_MODIFY (see Sections 1.6.1, 1.6.3, and 1.6.4). 


Input Parameters 


The read or write attributes subfunction is controlled by the attribute list 
specified by P5. The list consists of a variable number of two longword 
control blocks, terminated by a 0 longword, as shown in Figure 1-6. The 
maximum number of attribute control blocks in one list is 30. Table 1-6 
describes the attribute control block fields. 
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Figure 1-6 Attribute Control Block Format 


31 16 15 0 


ATR$W_TYPE ATR$W_SIZE 
ATR$L_ADDR | 


(Additional Control Blocks) 










ZK-0640—GE 
Table 1-6 Attribute Control Block Fields 
Field Meaning 
ATR$W_SIZE Specifies the number of bytes of the attribute to be 


transferred. Legal values are from 0 to the maximum size of 
the particular attribute (see Table 1-7). 


ATR$SW_TYPE Identifies the individual attribute to be read or written. 


ATR$L_ADDR Contains the buffer address of the memory space to or from 
which the attribute is to be transferred. The attribute buffer 
must be writable. 


Table 1-7 lists the valid attributes for ACP-QIO functions. The maximum 
size (in bytes) is determined by the required attribute configuration. For 
example, the Radix—50 file name (ATR$S_FILNAM) uses only 6 bytes, but 
it is always accompanied by the file type and file version, so a total of 10 
bytes is required. Each attribute has two names: one for the code (for 
example, ATR$C_UCHAR) and one for the size (for example, 
ATR$S_UCHAR). 
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Table 1-7 ACP—dQIO Attributes 


Maximum 
Size 

Attribute Name’ (bytes) Meaning 

ATR$C_UCHAR? 4 4 4-byie file characteristics. (The file 
characteristics bits are listed following 
this table.) 

ATR$C_RECATTR® 32 Record attribute area. Section 1.4 
describes the record attribute area in 
detail. 

ATR$C_FILNAM 10 6-byte Radix—50 file name plus 
ATR$C_FILTYP and ATR$C_FILVER. 

ATR$C_FILTYP 4 2-byte Radix—50 file type plus 
ATR$C_FILVER. 

ATR$C_FILVER 2 2-byte binary version number. 

ATR$C_EXPDAT? 7 Expiration date in ASCII. Format: 
DDMMMYVY. 

ATR$C_STATBLK® 32 Statistics block. Section 1.5 
describes the statistics block in 
detail. 

ATR$C_HEADER?® 512 Complete file header. 

ATR$C_BLOCKSIZE 2 Magnetic tape block size. 

ATR$C_USERLABEL® 80 User file label. 

ATR$C_ASCDATES? 4 35 Revision count (2 binary bytes), 
revision date, creation date, and 
expiration date, in ASCII. Format: 
DDMMMYY (revision date), HHMMSS 
(time), DDMMMYY (creation date), 
HHMMSS (time), DDMMMYY 
(expiration date). (The format 
contains no embedded spaces or 
commas.) 

ATR$C_ALCONTROL 14 Compatibility mode allocation data. 

ATR$C_ENDLBLAST 4 End of magnetic tape label 
processing; provides AST control 
block. 


‘Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the code 
and one with an ATR$S_ prefix for the size, which is not included in the list. 


2Protected (can be written to only by system or owner). 

3Locked (cannot be written to while the file is locked against writers). 

4Not supported on write operations to MTAACP; defaults are returned on read operations. 
5Read only. 


SNot supported for disk devices. 


(continued on next page) 
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Table 1-7 (Cont.) ACP—QIO Attributes 


Attribute Name’ 
ATR$C_ASCNAME 


ATR$C_CREDATE? 
ATR$C_REVDATE? ° 
ATR$C_EXPDATE? 
ATR$C_BAKDATE® 1° 
ATR$C_UIC? 
ATR$C_FPRO? ° 
ATR$C_RPRO” 
ATR$C_ACLEVEL? 3 1° 
ATR$C_SEMASK"? 
ATR$C_UIC_RO® 
ATR$C_DIRSEQ"® 
ATR$C_BACKLINK’? 
ATR$C_JOURNAL”® 
ATR$C_HDR1_ACC 


ATR$C_ADDACLENT’ *° ™ 


ATR$C_DELACLENT’ '° " 
ATR$C_MODACLENT’ *° ™ 


Maximum 
Size 
(bytes) 
20 


-~ NON F&F DO A NY YO FH CO WO CO © 


255 


255 
255 
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Meaning 


Disk: file name, type, and version, in 
ASCIl, including punctuation. Format: 
name.type;version. 


Magnetic tape: contains 17-character 
file identifier (ANSI a); no version 
number. Overrides all other file name 
and file type specifications if supplied 
on input operations. If specified on 
an access operation and you want 
only a value to be returned, specify 
(in ATR$W_SIZE) a buffer of greater 
than 17 bytes. 


64-bit creation date and time. 
64-bit revision date and time. 
64-bit expiration date and time. 
64-bit backup date and time. 
4-byte file owner UIC. 

File protection. 

2-byte record protection. 

File access level. 

File security mask and limit. 
4-byte file owner UIC. 
Directory update sequence count. 
File back link pointer. 

Journal control flags. 


ANSI magnetic tape header label 
accessibility character. 


Add one or more access control 
entries. 


Remove an access control entry. 
Modify an ACL entry. 


‘Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the code 
and one with an ATR$S__ prefix for the size, which is not included in the list. 


2Protected (can be written to only by system or owner). 


3Locked (cannot be written to while the file is locked against writers). 


5Read only. 


7Exclusive access required. This operation does not complete successfully if other readers or 


writers are allowed. 


'ONot supported for Files—11 On-Disk Structure Level 1 or magnetic tapes. 
"The status from this attribute operation is returned in FIB$L_ACL_STATUS. 


(continued on next page) 
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Table 1-7 (Cont.) ACP—QIO Attributes 


Maximum 
Size 
Attribute Name’ (bytes) Meaning 
ATR$C_FNDACLENT"? " 255 Locate an ACL entry. 
ATR$C_FNDACETYP’? " 255 Find a specific type of ACE. 
ATR$C_DELETEACL’ '° " 255 Delete the entire ACL, retaining any 
unprotected entries. 
ATR$C_READACL"® " 512 Read the entire ACL or as much as 
will fit in the supplied buffer. Only 
complete ACEs are transferred. 
Thus, the supplied buffer can not be 
completely filled. 
ATR$C_ACLLENGTH”® * 4 Return the length of the ACL. 
ATR$C_READACE"? 255 Read a single ACE. 
ATR$C_RESERVED® '° 380 Modify reserve area. 
ATR$C_HIGHWATER"® 4 High-water mark (user read-only). 
ATR$C_PRIVS_USED® ' 4 Privileges used to gain access. 
ATR$C_MATCHING_ACE® ' = 255 ACE used to gain access (if any). 
ATR$C_ACCESS_ MODE 1 Access mode for following attribute 
descriptors. 
ATR$C_FILE_SPEC'® 512 Convert FID to file specification. 
ATR$C_BUFFER_OFFSET* 2 Offset length for ANSI magnetic tape 
header label buffer. 
ATR$C_DELETE_ALL7'0" 255 Delete the entire ACL. 
ATR$C_GRANT_ACE"®"! 255 Return an ACE which grants or 
denies access. 
ATR$C_NEXT_ACE"®" 4 Step on to point to the next ACE in 
the ACL. 


‘Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the code 
and one with an ATR$S__ prefix for the size, which is not included in the list. 


4Not supported on write operations to MTAACP; defaults are returned on read operations. 


7Exclusive access required. This operation does not complete successfully if other readers or 
writers are allowed. 


8This attribute can only be retrieved on the initial file access or create operation. 


°The actual length available can decrease if the file is extended in a noncontiguous manner or if 
an ACL is applied to the file. 


'ONot supported for Files—11 On-Disk Structure Level 1 or magnetic tapes. 
"The status from this attribute operation is returned in FIB$L_ACL_STATUS. 


Table 1-8 lists the bits contained in the file characteristics longword, 
which is read with the ATR$C_UCHAR attribute. 
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Table 1-8 File Characteristics Bits 


FCHNOBACKUP File is not to be backed up. 
FCH$M_READCHECK Verify all read operations. 
FCH$M_WRITCHECK Verify all write operations. 


FCH$M_CONTIGB Keep file as contiguous as possible. 
FCH$M_LOCKED File is deaccess-locked. 
FCH$M_CONTIG File is contiguous. 
FCH$M_BADACL File’s ACL is corrupt. 
FCH$M_SPOOL File is an intermediate spool file. 
FCH$M_DIRECTORY File is a directory. 
FCH$M_BADBLOCK File contains bad blocks. 
FCH$M_MARKDEL File is marked for deletion. 
FCH$M_ERASE Erase file contents before deletion. 





1.4 ACP QIO Record Attributes Area 


Figure 1-7 shows the format of the record attributes area. 
Figure 1-7 ACP—QIO Record Attributes Area 


31 24 23 16 15 8 7 0 


FAT$W_RSIZE FAT$B_RATTRIB FAT$B_RTYPE* 












(6 Bytes Reserved for Future Use) or 

. 
*FAT$V_RTYPE Bits 0-3; FAT$V_FILEORG Bits 4-7 

ZK-0641-GE 
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Table 1-9 lists the record attributes values and their meanings. 


Table 1-9 ACP Record Attributes Values 


Field Value 
FAT$B_RTYPE 


FAT$V_RTYPE 


FAT$V_FILEORG 


FAT$B_RATTRIB 


FAT$W_RSIZE 
FAT$L_HIBLK? 


FAT$L_EFBLK? ° 


FAT$W_FFBYTE® 
FAT$B_BKTSIZE 


Meaning 


Record type. Contains FAT$V_RTYPE and 
FAT$V_FILEORG. 


Record type. The following bit values are defined: 


FAT$C_FIXED Fixed-length record 

FAT$C_VARIABLE Variable-length record 

FAT$C_VFC Variable-length record with fixed 
control 

FAT$C_UNDEFINED — Undefined record format (stream 
binary) 

FAT$C_STREAM RMS stream format 


FAT$C_STREAMLF Stream terminated by LF 
FAT$C_STREAMCR Stream terminated by CR 


File organization. The following bit values are defined: 
FAT$C_DIRECT Direct file organization’ 


FAT$C_INDEXED Indexed file organization 
FAT$C_RELATIVE Relative file organization 
FAT$C_SEQUENTIAL Sequential file organization 


Record attributes. The following bit values are defined: 
FAT$M_FORTRANCC FORTRAN carriage conirol 


FAT$M_IMPLIEDCC Implied carriage control 
FAT$M_PRINTCC Print file carriage control 
FAT$M_NOSPAN No spanned records 
Record size in bytes. 


Highest allocated VBN. The ACP maintains this field when 
the file is extended or truncated. Attempts to modify this field 
in a write attributes operation are ignored. 


FAT$W_HIBLKH High-order 16 bits 
FAT$W_HIBLKL Low-order 16 bits 
End-of-file VBN 

FAT$W_EFBLKH High-order 16 bits 
FAT$W_EFBLKL Low-order 16 bits 


First free byte in FAT$L_EFBLK. 
Bucket size in blocks. 


'Defined but not implemented. 


2Inverted format field. The high- and low-order 16 bits are transposed for compatibility with 


PDP—11 software. 


3When the end-of-file position corresponds to a block boundary, by convention 
FAT$L_EFBLK contains the end-of-file VBN plus 1, and FAT$W_FFBYTE contains 0. 
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Table 1-9 (Cont.) ACP Record Attributes Values 


Field Value Meaning 

FAT$B_VFCSIZE Size in bytes of fixed-length control for VFC records. 
FAT$W_MAXREC Maximum record size in bytes. 

FAT$W_DEFEXT Default extend quantity. 

FAT$W_GBC Global buffer count. 


FAT$W_VERSIONS Default version limit; valid only if the file is a directory. 


1.5 ACP-QIO Attributes Statistics Block 


Figure 1-8 shows the format of the attributes statistics block. Table 1-10 
lists the contents of this block. 


Figure 1-8 ACP-QIO Attributes Statistics Block 
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Table 1-10 Contents of the Statistics Block 
Field Field Values Meaning 
SBK$L_STLBN Contains the starting LBN of the file if the file is contiguous. If the 


file is not contiguous, this field contains a value of 0. The LBN 
appears as an inverted longword (the high- and low-order 16 bits 
are transposed for PDP—11 compatibility). The following subfields 
are defined: 


(continued on next page) 
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Table 1-10 (Cont.) Contents of the Statistics Block 
Field Field Values Meaning 


SBK$W_STLBNH Starting LBN (high-order 16 bits). 
SBK$W_STLBNL Starting LBN (low-order 16 bits). 


SBK$L_FILESIZE Contains the size of the file in blocks. The file size appears as an 
inverted longword (the high- and low-order 16 bits are transposed 
for PDP—11 compatibility). The following subfields are defined: 


SBK$W_FILESIZH File size (high-order 16 bits). 
SBK$W_FILESIZL File size (low-order 16 bits). 


SBK$B_ACNT' Access count (low byte). Field is for PDP—11 compatibility. 

SBK$B_LCNT' Lock count (low byte). Field is for PDP—11 compatibility. 

SBK$L_FCB System pool address of the file’s file control block. 

SBK$W_ACNT' Access count (number of channels with file open currently). 

SBK$W_LCNT' Lock count (the number of access operations that have locked the 
file against writers). 

SBK$W_WCNT' Writer count (the number of channels that currently have the file 
open for write). 

SBK$W_TCNT' Truncate lock count (the number of access operations that have 
locked the file against truncation). 

SBK$L_READS Number of read operations executed for file on this channel. 

SBK$L_WRITES Number of write operations executed for file on this channel. 


1 Accesses from processes on the local node in a cluster are counted. 





Major Functions 


The following sections describe the operation of the major ACP functions. 
Each section describes the required and optional parameters for a 
particular function, as well as the sequence in which the function is 
performed. For clarity, when a major function invokes a subfunction, the 
input parameters used by the subfunction are omitted. 


Create File 


Create file is a virtual I/O function that creates a directory entry or a file 
on a disk device, or a file on a magnetic tape device. 


The following is the function code: 
¢ IO$ CREATE 
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The following are the function modifiers: 


IO$M_CREATE—Creates a file. 
IO$M_ACCESS—Opens the file on your channel. 


IO$M_DELETE—Marks the file for deletion (applicable only to disk 
devices). 


Input Parameters 


The following are the device- or function-dependent arguments for 
IO0$_CREATE: 


P1—tThe address of the file information block (FIB) descriptor. 
P2—The address of the file name string descriptor (optional). 


P3—The address of the word that is to receive the length of the 
resultant file name string (optional). 


P4—The address of a descriptor for a buffer that is to receive the 
resultant file name string (optional). 


P5—The address of a list of attribute descriptors (optional). 


Table 1—11 lists fields in the FIB that are applicable to the IO$_CREATE 
operation. 


Table 1-11 1IO$ CREATE and the File Information Block 


Field 
FIB$L_ACCTL 


FIB$W_CNTRLFUNC 


Field Values Meaning 


Specifies field values that control access to the file. The 
following bits are applicable to the |O$_CREATE function: 


FIB$M_REWIND Set to rewind magnetic tape before creating the file. Any data 


currently on the tape is overwritten. 


FIB$SM_CURPOS Set to create magnetic tape file at the current tape position. 


(Note: a magnetic tape file is created at the end of the volume 
set if neither FIB$M_REWIND nor FIB$M_CURPOS is set.) If 
the tape is not positioned at the end of a file, FIB$M_CURPOS 
creates a file at the next file position. Any data currently on the 
tape past the current file position is overwritten. 


FIB$M_WRITETHRU _ Specifies that the file header is to be written back to the disk. If 


not specified and the file is opened, writing of the file header can 
be deferred to some later time. 


Specifies the following value, which allows you to control actions 
subsequent to EOT detection on a magnetic tape file. 


(continued on next page) 
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Table 1-11 (Cont.) I1O$ CREATE and the File Information Block 
Field Field Values Meaning 


FIB$C_USEREOT Set on a per-file basis to specify user EOT mode. If this 
bit is set, user EOT handling is enabled. When writing, if 
EOT has been detected (considered a “serious exception”) 
and user EOT handling is enabled, then the magnetic tape 
system returns the alternate success code SS$_ENDOFTAPE. 
When reading, if EOV is reached, then the alternate success 
code SS$_ENDOFVOLUME is returned. In either case, all 
subsequent I/O requests for the volume are completed with a 
failure status return of SS$_SERIOUSEXCP. The driver does not 
execute any I/O functions until the serious exception has been 
explicitly cleared by issuing an IO$_ACPCONTROL function 
(see Section 1.6.7). If the file is deaccessed or closed, the user 
EOT mode is cleared after further processing of the magnetic 
tape. 


FIB$W_FID Contains the file ID of the file created or entered. 
FIB$W_DID Contains the file identifier of the directory file. 


FIB$W_NMCTL Controls the processing of the file name in a directory operation. 
The following bits are applicable to the |O$_CREATE function: 


FIB$M_NEWVER Set to create file of same name with next higher version number. 
Only for disk devices. 


FIB$M_SUPERSEDE _ Set to supersede an existing file of the same name, type, and 
version. Only for disk devices. 


FIB$M_LOWVER Set on return if a lower numbered version of the file exists. Only 
for disk devices. 
FIB$M_HIGHVER Set on return if a higher numbered version of the file exists. 
Only for disk devices. 
FIB$W_VERLIMIT Specifies the version limit for the directory entry created. Used 


only for disk devices and only when the first version of a new 
file is created. If 0, the directory default is used. If a directory 
operation was performed, FIB$W_VERLIMIT always contains 
the actual version limit of the file. 


FIB$L_ACL_STATUS Status of the requested ACL attribute operation, if any. The ACL 
attributes are included in Table 1-7. If no ACL attributes are 
given, SS$_NORMAL is returned here. 





1.6.1.2 Disk ACP Operation 
If the modifier IO$M_CREATE is specified, a file is created. The file ID of 
the file created is returned in FIB$W_FID. If the modifier IO$M_DELETE 
is specified, the file is marked for deletion. 


If a nonzero directory ID is specified in FIB$W_DID, a directory entry 

is created. The file name specified by parameter P2 is entered in the 
directory, together with the file ID in FIB$W_FID. (Section 1.3.1.1 
describes the format for the file name string.) Wildcards are not permitted. 
Negative version numbers are treated as equivalent to a 0 version number. 
If a result string buffer and length are specified by P3 and P4, the actual 
file name entered, and its length, are returned. 
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The version number of the file receives the following treatment: 


¢ Ifthe version number in the specified file name is 0 or negative, the 
directory entry created gets a version number one greater than the 
highest previously existing version of that file (or version 1 if the file 
did not previously exist). 


e Ifthe version number in the specified file name is a nonzero number 
and FIB$M_NEWVER is set, the directory entry created gets a version 
number one greater than the highest previously existing version of 
that file, or the specified version number, whichever is greater. 


e Ifthe version number in the specified file name is a nonzero number 
and the directory already contains a file of the same name, type, 
and version, the previously existing file is set aside for deletion if 
FIB$M_SUPERSEDE is specified. If FIB$M_SUPERSEDE is not 
specified, the create operation fails with an SS$_DUPFILNAM status. 


e If, after creating the new directory entry, the number of versions of the 
file exceeds the version limit, the lowest numbered version is set aside 
for deletion. 


e Ifthe file did not previously exist, the new directory entry is 
given a version limit as follows: the version limit is taken from 
FIB$W_VERLIMIT if it is a nonzero number; if it is 0, the version 
limit is taken from the default version limit. of the directory file; if the 
default version limit of the directory file is 0, the version limit is set to 
32,767 (the highest possible number). 


The file name string entered in the directory is returned using the P3 
and P4 result string parameters, if present. The file name string is 

also written into the header. If no directory operation was requested 
(FIB$W_DID is 0), the file name string specified by P2, if any, is written 
into the file header. 


If an attribute list is specified by P5, a write attributes subfunction is 
performed (see Section 1.3.5). 


If the modifier IO$M_ACCESS is specified, the file is opened (see 
Section 1.3.2). 


If the extend enable bit FIB$M_EXTEND is specified in the FIB, an extend 
subfunction is performed (see Section 1.3.3). 


Finally, if a file was set aside for deletion (IO$M_DELETE is specified), 
that file is deleted. If the file is deleted because the FIB$M_SUPERSEDE 
bit was set, the alternate success status SS$_SUPERSEDE is returned in 
the I/O status block. If the file is deleted because the version limit was 
exceeded, the alternate success status SS$_FILEPURGED is returned. 


If an error occurs in the operation of an IO$_CREATE function, all actions 
performed to that point are reversed (the file is neither created nor 
changed), and the error status is returned to the user in the I/O status 
block. 
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1.6.1.3 Directory Entry Creation 


Creating a new version of a file eliminates default access to the previously 
highest version of the file. For example, creating RESUME.TXT;4 masks 
RESUME.TXT;3 so that the DCL command TYPE RESUME.TXT yields 
the contents of version 4, not version 3. To protect the contents of the 
earlier version of a file, the creator of a file must have write access to the 
previous version of a file of the same name. 


1.6.1.4 Magnetic Tape ACP Operation 


Access File 


1.6.2.1 
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No operation is performed unless the IO$M_CREATE modifier is specified. 
The magnetic tape is positioned as specified by FIB${M_REWIND and 
FIB$M_CURPOS, and the file is created. The name specified by the P2 
parameter is written into the file header label. 


If P5 specifies an attribute list, a write attributes subfunction is performed 
(see Section 1.3.5). 


If the modifier IO$M_ACCESS is specified, the file is opened (see 
Section 1.3.2). 


This virtual I/O function searches a directory on a disk device or a 
magnetic tape for a specified file and accesses that file if found. 


The following is the function code: 
e IO$_ACCESS 


The following are the function modifiers: 
¢ JO$M_CREATE—Creates a file. 
e JIO$M_ACCESS—Opens the file on your channel. 


Input Parameters 


The following are the device- or function-dependent arguments for 
I0$_ACCESS: 


e P1—tThe address of the file information block (FIB) descriptor. 
¢ P2—The address of the file name string descriptor (optional). 


e P3—The address of the word that is to receive the length of the 
resultant file name string (optional). 


e P4—The address of a descriptor for a buffer that is to receive the 
resultant file name string (optional). 


e P5—The address of a list of attribute descriptors (optional). 


Table 1-12 lists FIB fields that are applicable to the IO$_ACCESS 
operation. 
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Table 1-12 1!O$ ACCESS and the File Information Block 


Field 
FIBSW_CNTRLFUNC 


FIB$W_VERLIMIT 


FIB$L_ACL_STATUS 


FIB$L_STATUS 


FIB$L_ALT_ACCESS 


Field Values Meaning 


Specifies the value that allows the user to control actions 
subsequent to EOT detection on a magnetic tape file. 


FIB$C_USEREOT Set on a per-file basis to specify user EOT mode. If this bit 


is set, the magnetic tape driver notifies the magnetic tape 
system when EOT has been detected (considered a “serious 
exception”) when a file is accessed. In turn, the magnetic tape 
system returns the alternate success code SS$_ENDOFTAPE 
or SS$_ENDOFVOLUME. All subsequent I/O requests are 
completed with a failure status return of SS$_ SERIOUSEXP. 
The driver does not execute any I/O functions until the serious 
exception has been explicitly cleared by issuing an 
lO$_ACPCONTROL function (see Section 1.6.7). If the file 

is deaccessed or closed, the user EOT mode is cleared after 
further processing of the magnetic tape. 


Receives the version limit for the file. Applicable only if 
FIB$W_DID is a nonzero number (if a directory lookup is done). 
Used only for disk devices. 


Status of the requested ACL attribute operation, if any. The ACL 
attributes are included in Table 1-7. If no ACL attributes are 
given, SS$_NORMAL is returned here. 


Alternate access status. The following bits are supported: 


FIB$V_ALT_REQ Set to indicate whether the alternate access bit is required for 
the current operation. If not set, the alternate access bit is 
optional. 

FIB$V_ALT_ lf FIB6V_ALT_REQ = 0 and the alternate access check 

GRANTED succeeded, the FIB bit returned from the file system is set. 


A 32-bit mask that represents an access mask to check against 
file protection; for example, to open a file for read and to check 

whether it can be deleted. The mask has the same configuration 
as the standard protection mask. 





1.6.2.2 Operation 


If a nonzero directory file ID is specified in FIB$W_DID, a lookup 
subfunction is performed (see Section 1.3.1.) The version limit of the 
file found is returned in FIB$W_VERLIMIT. 


If the directory search fails with a ’ file not found’ condition and the 
IO$M_CREATE function modifier is specified, the function is reexecuted as 
a CREATE. In that case, the argument interpretations for IO$_CREATE, 
rather than those for IO$_ACCESS, apply. 


If IO$M_ACCESS is specified, an access subfunction is performed to open 
the file (see Section 1.3.2). 


If P5 specifies an attribute list, a read attributes subfunction is performed 
(see Section 1.3.5). 
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Deaccess File 


Deaccess file is a virtual I/O function that deaccesses a file and, if specified, 
writes final attributes in the file header. 


The following is the function code: 
¢ IO$_DEACCESS 


I0$_DEACCESS takes no function modifiers. 


1.6.3.1 Input Parameters 


The following are the device- or function-dependent arguments for 
IO0$_DEACCESS: 


e P1—The address of the file information block (FIB) descriptor. 
¢ P5—The address of a list of attribute descriptors (optional). 


The following FIB field is applicable to a IO$_DEACCESS function: 


Field Meaning 


FIB$W_FID File identification of the file being deaccessed. This field can 
contain a value of 0. If it does not, it must match the file 
identifier of the accessed file. 


FIB$L_ACL_STATUS _ Status of the requested ACL attribute operation, if any. The 


ACL attributes are included in Table 1-7. If no ACL attributes 
are given, SS$_NORMAL is returned here. 


1.6.3.2 Operation 


Modify File 


1-28 


For disk files, if P5 specifies an attribute control list and the file was 
accessed for a write operation, a write attributes subfunction is performed 
(see Section 1.3.5). If the file was opened for write, no attributes were 
specified, and FIB$M_DLOCK was set when the file was accessed, the 


deaccess lock bit is set in the file header, inhibiting further access to that 
file. 


For disk files, if the truncate enable bit FIB$M_TRUNCATE is specified in 
the FIB, a truncate subfunction is performed (see Section 1.3.4). 


Finally, the file is closed. Trailer labels are written for a magnetic tape file 
that was opened for write. 


Modify file is a virtual I/O function that modifies the file attributes or 
allocation of a disk file. The IO$_MODIFY function is not applicable to 
magnetic tape. 


The following is the function function code: 


e JO$ MODIFY 
I0$_MODIFY takes no function modifiers. 


1.6.5 


1.6.4.1 


Field 
FIB$L_ACCTL 


FIB$W_VERLIMIT 
FIB$L_ACL_STATUS 
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Input Parameters 


The following are the device- or function-dependent arguments for 
10$_MODIFY: 


e Pi—The address of the file information block (FIB) descriptor. 


e P2—The address of the file name string descriptor (optional). If 
specified, the directory is searched for the name. 


¢ P3—The address of the word that is to receive the length of the 
resultant file name string (optional). 


e P4—The address of a descriptor for a buffer that is to receive the 
resultant file name string (optional). 


e P5—The address of a list of attribute descriptors (optional). 
The following FIB fields are applicable to the IO$_MODIFY function: 


Field Values Meaning 


Specifies field values that control access to the file. The 
following bits are applicable to the 1O0$_ MODIFY function: 


FIB$M_WRITETHRU _ Specifies that the file header is to be written back to the disk. 


If not specified and the file is currently open, writing of the file 
header can be deferred to some later time. 


If a nonzero number, specifies the version limit for the file. 


Status of the requested ACL attribute operation, if any. The ACL 
attributes are included in Table 1~7. If no ACL attributes are 
given, SS$_ NORMAL is returned here. 


1.6.4.2 Operation 


Delete File 


If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction 
is executed (see Section 1.3.1). If a nonzero version limit is specified in 
FIB$W_VERLIMIT and the directory entry found is the latest version of 
that file, the version limit is set to the value specified. 


If P5 specifies an attribute list, a write attributes subfunction is performed 
(see Section 1.3.5). 


The file can be either extended or truncated. If FIB$}M_EXTEND is 
specified in the FIB, an extend subfunction is performed (see Section 1.3.3). 
If FIB${M_TRUNCATE is specified in the FIB, a truncate subfunction is 
performed (see Section 1.3.4). Extend and truncate operations cannot be 
performed at the same time. . 


Delete file is a virtual I/O function that removes a directory entry or file 
header from a disk volume. 


The following is the function code: 
e JIO$_DELETE 
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Field 
FIB$L_ACCTL 


FIB$W_FID 


1.6.5.1 


Mount 


ACP Control 
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The following is the function modifier: 
¢ JO$M_DELETE—Deletes the file (or marks it for deletion). 


The following are the device- or function-dependent arguments for 
I0$_DELETE: 


¢ P1—The address of the file information block (FIB) descriptor. 
¢ P2—The address of the file name string descriptor (optional). 


¢ P3—The address of the word that is to receive the length of the 
resultant file name string (optional). 


¢ P4—The address of a descriptor for a buffer that is to receive the 
resultant file name string (optional). 


The following FIB fields are applicable to the IO$_DELETE function: 


Field Values Meaning 


Specifies field values that control access to the file. The 
following bit is applicable to the 1O$_DELETE function: 


FIBSM_WRITETHRU Specifies that the file header is to be written back to the disk. 


If not specified and the file is currently open, writing of the file 
header can be deferred to some later time. 


Specifies the file identification to be deleted. 


Operation 


If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction 
is performed (see Section 1.3.1). The file name located is removed from the 
directory. 


If the function modifier IO$M_DELETE is specified, the file is marked for 
deletion. If the file is not currently open, it is deleted immediately. If the 
file is open, it is deleted when the last accessor closes it. 


Mount is a virtual I/O function that informs the ACP when a disk or 
magnetic tape volume is mounted. MOUNT privilege is required. 
IO$_MOUNT takes no arguments or function modifiers. This function 
is a part of the volume mounting operation only, and it is not meant for 
general use. Most of the actual processing is performed by the MOUNT 
command or the Mount Volume (S$MOUNT) system service. 


ACP Control is a virtual I/O function that performs miscellaneous control 
functions, depending on the arguments specified. 


The following is the function code: 
¢ I0$_ACPCONTROL 
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The following is the function modifier: 
¢ IO$M_DMOUNT—Dismounts a volume. 


1.6.7.1. Input Parameters 


The following are the device- or function-dependent arguments for 


I0$_ACPCONTROL: 


¢ P1—The address of the file information block (FIB) descriptor. 
e P2—The address of the file name string descriptor (optional). 


¢ P38—The address of the word that is to receive the length of the 
resultant file name string (optional). 


¢ P4—The address of a descriptor for a buffer that is to receive the 
resultant file name string (optional). 


Table 1-13 lists FIB fields that control the processing of the 
I0$_ACPCONTROL function. 


Table 1-13 IO$ ACPCONTROL and the File Information Block 


Field Field Values 
FIB$W_CNTRLFUNC 


FIB$L_CNTRLVAL 


FIB$L_ACL_STATUS 


FIB$L_STATUS 


FIB$V_ALT_REQ 


FIB$V_ALT_GRANTED 


FIB$L_ALT_ACCESS 


Meaning 


Specifies the control function to be performed. This field 
overlays FIB6W_EXCTL. 


Specifies additional function-dependent data. This field 
overlays FIB$L_EXSZ. 


Status of the requested ACL attribute operation, if any. 
The ACL attributes are included in Table 1-7. If no ACL 
attributes are given, SS$_ NORMAL is returned here. 


Alternate access status. The following bits are supported: 


Set to indicate whether the alternate access bit is required 
for the current operation. If not set, the alternate access bit 
is optional. 


If FIB$V_ALT_REQ = 0 and the alternate access check 
succeeded, the FIB bit returned from the file system is set. 


A 32-bit mask that represents an access mask to check 
against file protection; for example, to open a file for read 
and to check whether it can be deleted or not. The mask 
has the same configuration as the standard protection 
mask. 


1.6.7.2 Magnetic Tape Control Functions 
Table 1-14 lists FIB field applicable to magnetic tape operations. 
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Table 1-14 Magnetic Tape Operations and the File Information Block 


Field 


Field Values 


FIB$SW_CNTRLFUNC 


FIB$C_REWINDFIL 
FIB$C_REWINDVOL 
FIB$C_POSEND 
FIB$C_NEXTVOL 
FIB$C_SPACE 


FIB$C_CLSEREXCP 


Meaning 


Several ACP conirol functions are used for magnetic tape 
positioning. These functions are specified by supplying a FIB 
with P1 containing the FIB descriptor address. Modifiers and 
parameters P2, P3, and P4 are not allowed. These functions 
clear serious exceptions in magnetic tape drivers. The following 
control functions can be specified to control magnetic tape 
positioning: 

Rewind to beginning-of-file. 

Rewind to beginning-of-volume set. 

Position to end-of-volume set. 

Force next volume. 


Space n blocks forward or backward. The FIB$L_CNTRLVAL 
field specifies the number of magnetic tape blocks to space 
forward if positive or to space backward if negative. 


If set, clears the serious exception in the magnetic tape driver 
(see FIB$C_USEREOT in Section 1.6.1 and Section 1.6.2). If 
writing, this allows the user to write data blocks beyond the EOT 
marker, which can result in the magnetic tape not conforming 

to the ANSI standard for magnetic tapes (see ANSI Standard 
X3.27-1978). If reading, this allows the user to handle the move 
to the next volume or to stop reading the tape. The user should 
not attempt to read past EOV. 
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1.6.7.3. Miscellaneous Disk Control Functions 


Several ACP control functions are available for disk volume control. The 
following function does not use parameters P2, P38, and P4: 


1O$M_DMOUNT 


Specifying the dismount modifier on the 1O$_ ACPCNTRL 
function executes a dismount QIO. No parameters in the 
FIB are used; the FIB can be omitted. This function does 
not perform a dismount by itself, but is used to synchronize 
the ACP with the DISMOUNT command and the Dismount 
Volume (SDISMOUNT) system service. 


The FIB$}W_CNTRLFUNC field of the FIB specifies the following 
miscellaneous control functions (with no modifier on the IO$_ 
ACPCONTROL function code). These functions use no other parameters. 


FIB$C_REMAP 


Remap a file. The file window for the file open on the user’s 
channel is remapped so that it maps the entire file. 
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FIB$C_LOCK_VOL Allocation lock the volume. Operations that change the file 
structure, such as file creation, deletion, extension, and 
deaccess, are not permitted. If such requests are queued to 
the file system for an allocation-locked volume, they are not 
processed until the FIB$C_UNLK_VOL function is issued to 
unlock the volume. 


To issue the FIB$C_LOCK_VOL function, you must have 
either a system UIC or SYSPRV privilege, or be the owner of 
the volume. 

FIB$C_UNLK_VOL Unlock the volume. Cancels FIB$C_LOCK_VOL. To issue 
this function, you must have either a system UIC or SYSPRV 
privilege, or be the owner of the volume. 


1.6.7.4 Disk Quotas 


Disk quota enforcement is enabled by a quota file on the volume, or 

relative volume 1 if the file is on a volume set. The quota file appears in 
the volume’s master file directory (MFD) under the name QUOTA.SY§;1. 
This section describes the control functions that operate on the quota file. 


Table 1-15 lists the enable and disable quota control functions. 


Table 1-15 Disk Quota Functions (Enable/Disable) 


Value 


FIB$C_ENA_QUOTA 


FIB$6C_DSA_QUOTA 


Meaning 


Enable the disk quota file. If a nonzero directory file ID is specified in FIB$W_DID, a 
lookup subfunction is performed to locate the quota file (see Section 1.3.1). To issue 
this function, you must have either a system UIC or SYSPRV privilege, or be the 
owner of the volume. 

The quota file specified by FIB$W_FID, if present, is accessed by the ACP, and quota 
enforcement is turned on. By convention, the quota file is named [0,0JQUOTA.SYS;1. 
Therefore, FIB$W_DID should contain the value 4,4,0 and the name string specified 
with P2 should be “QUOTA.SYS;1”. 


Disable the disk quota file. The quota file is deaccessed and quota enforcement is 
turned off. To issue this function, you must have either a system UIC or SYSPRV 
privilege, or be the owner of the volume. 


Table 1-16 lists the quota control functions that operate on individual 
entries in the quota file. Each operation transfers quota file data to and 
from the ACP using a quota data block. This block has the same format as 
a record in the quota file. Figure 1-9 shows the format of this block. 


10$_ACPCONTROL functions that transfer quota file data between 
the caller and the ACP use the following device- or function-dependent 
arguments: 


e P2—The address of a descriptor for the quota data block being sent to 
the ACP. 


e P3—The address of a word that returns the data length. 


¢ .P4—The address of a descriptor for a buffer to receive the quota data 
block returned from the ACP. 
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Table 1-16 Disk Quota Functions (Individual Entries) 





Value 


FIB$C_ADD_QUOTA 


FIB$C_EXA_QUOTA 


FIB$C_MOD_QUOTA 


FIB$C_REM_QUOTA 
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Meaning 


Add an eniry to the disk quota file, using the UIC and quota specified in the P2 
argument block. FIB$C_ADD_QUOTA requires write access to the quota file. 


Examine a disk quota file entry. The entry whose UIC is specified in the P2 argument 
block is returned in the P4 argument block, and its length is returned in the P3 
argument word. Using two flags in FIB$L_CNTRLVAL, it is possible to search 
through the quota file using wildcards. The two flags are: 


FIB$M_ALL_MEM Match all UIC members 
FIB$M_ALL_GRP Match all UIC groups 


The ACP maintains position context in FIB$L_WCC. On the first examine call, you 
specify 0 in FIB$L_WCC; the ACP returns a nonzero value so that each succeeding 
examine call returns the next matching entry. 


Read access to the quota file is required to examine all non-user entries. 


Modify a disk quota file entry. The quota file entry specified by the UIC in the P2 
argument block is modified according to the values in the block, as controlled by 
three flags in FIB$6L_CNTRLVAL: 


FIBSM_MOD_PERM Change the permanent quota 
FIBSM_MOD_OVER Change the overdraft quota 
FIB$M_MOD_USE Change the usage data 


The usage data can be changed only if the volume is locked by FIB$C_LOCK_VOL 
(see Section 1.6.7.3). FIBSC_MOD_QUOTA requires write access to the quota file. 
The P3 and P4 arguments return the modified quota entry to you. 


By using the flags FIBSM_ALL_MEM and FIB$M_ALL_GRP, you can search through 
the quota file using wildcards just as you would with the FIB6C_EXA_QUOTA 
function. 


Remove a disk quota file entry whose UIC is specified in the P2 argument block. 
FIB$C_REM_QUOTA requires write access to the quota file. 


The P3 and P4 arguments return the removed quota file entry to you. 


By using the flags FIB$M_ALL_MEM and FIB$M_ALL_GRP, you can search through 
the quota file using wildcards just as you would with the FIBC_EXAQUOTA function. 
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Figure 1-9 Quota File Transfer Block 


31 0 


(Reserved for Future Use) 
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Figure 1-10 shows the I/O status block (IOSB) for ACP—QIO functions. 
Appendix A lists the status returns for these functions. (The VMS 
System Messages and Recovery Procedures Reference Manual provides 
explanations and suggested user actions for these returns.) 


The file ACP returns a completion status in the first longword of the IOSB. 
In an extend operation, the second longword is used to return the number 
of blocks allocated to the file. If a contiguous extend operation 
(FIB$M_ALCON) fails, the second longword is used to return the size of 
the file after truncation. 


Values returned in the IOSB are most useful during operations in 
compatibility mode. When executing programs in the native mode, use 
the values returned in FIB locations. 


Figure 1-10 !OSB Contents - ACP—QIO Functions 


+2 lIOSB 


Not Used 


+4 
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If an extend operation (including CREATE) was performed, IOSB+4 
contains the number of blocks allocated, or the largest available contiguous 
space if a contiguous extend operation failed. If a truncate operation was 
performed, IOSB+4 contains the number of blocks added to the file size to 
reach the next cluster boundary. 
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2.2.1 


Card Reader Driver 


This chapter describes the use of the VMS card reader driver that supports 


the CR11 card reader. 


Supported Card Reader Device 


The CR11 card reader reads standard 80-column punched data cards. 





Driver Features 


The VMS card reader driver provides the following features: 


¢ Support for multiple controllers of the same type; for example, more 
than one CR11 can be used on the system 


e Binary, packed Hollerith, and translated 026 or 029 read modes 
¢ Unsolicited interrupt support for automatic card reader input spooling 


e Special card punch combinations to indicate an end-of-file condition 
and to set the translation mode 


e Error recovery 
The following sections describe the read modes, special card punch 
combinations, and error recovery in greater detail. 


The VMS operating system provides the following card reader device- or 
function-dependent modifier bits for read data operations: 


¢ IO$M_PACKED—Read packed Hollerith code 
¢ IO$M_BINARY—Read binary code 


If IO$M_PACKED is set, the data is packed and stored in sequential bytes 
of the input buffer. If IO$M_BINARY is set, the data is read and stored 
in sequential words of the input buffer. IO$M_BINARY takes precedence 
over IO$M_PACKED. 


The read mode can also be set by a special card punch combination that 
sets the translation mode (see Section 2.2.1.2), or by the set mode function 
(see Section 2.4.3). 


Special Card Punch Combinations 


The VMS card reader driver recognizes three special card punch 
combinations in column 1 of a card. One combination signals an end- 
of-file condition. The other two combinations set the current translation 
mode. 
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2.2.1.1 


End-of-File Condition 


A card with the 12-11-0-1-6-7-8-9 holes punched in column 1 signals an 
end-of-file condition. If the read mode is binary, the first eight columns 
must contain that punch combination. 


2.2.1.2 Set Translation Mode 


If the read mode is nonbinary, nonpacked Hollerith (the IO$M_BINARY 
and IO$M_PACKED function modifiers are not set), the current 
translation mode can be set to the 026 or 029 punch code. (Table 2-5 lists 
the 026 and 029 punch codes.) A card with the 12-2-4-8 holes punched 
in column 1 sets the translation mode to the 026 code. A card with the 
12-0-2-4-6-8 holes punched in column 1 sets the translation mode to the 
029 code. The translation mode can be changed as often as required. 


If a translation mode card contains punched information in columns 2 
through 80, it is ignored. 


The system can read cards that were punched on an 026 punch or an 029 
punch. By default, the translation mode is 029; that is, the system reads 
cards from an 029 punch. However, you can change the translation mode 
by using the following: 


e¢ The SET CARD_READER command 
¢ Translation mode cards 
Use the SET CARD_READER command, with the /026 or /029 qualifier, 


to set the card reader to accept cards from either an 026 or an 029 card 
punch. 


Logical, virtual, and physical read functions result in only one card 
being read. If a translation mode card is read, the read function is not 
completed, and another card is read immediately. 


2.2.2 Submitting Batch Jobs Through the Card Reader 
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When you submit a batch job through a system card reader, precede the 
card deck containing the command procedure with cards containing JOB 
and PASSWORD commands. These cards specify your user name and 
password and, when executed, effect a login for you. The last card in 
the deck must contain the EOJ (End of Job) command. The EOJ card is 
equivalent to logging out. You can also use an overpunch card instead of 
an EKOJ card to signal the end of a job. To do this, use an EOF card 
(12-11-0-1-6-7-8-9) overpunch or use the EOJ command. Figure 2-1 
illustrates a card reader batch job. 


2.2.3 


2.2.4 


Error Recovery 
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Figure 2-1 A Card Reader Batch Job 








...Command Input Stream... 


$ PASSWORD HENRY 
$ JOB HIGGINS 
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When the system reads a job from the card reader, it validates the 

user name and password specified on the JOB and PASSWORD cards. 
Then, it copies the entire card deck into a temporary disk file named 
INPBATCH.COM in your default disk and directory, and it queues the 
job for batch execution. Thereafter, processing is the same as for jobs 
submitted interactively with the SUBMIT command. When the batch job 
is completed, the operating system deletes the INPBATCH.COM file. 


You can prevent other users from seeing your password by suppressing 
printing when you keypunch the PASSWORD card. 


Passing Data to Commands and Images 


To pass data to commands and images in batch jobs that you submit 
through a card reader, you can do the following: 


¢ Include the data in the command procedure by placing the data on the 
lines after the command or image that uses the data. Use the DECK 
and EOD commands if the data lines begin with dollar signs. 


¢ Temporarily redefine SYS$INPUT as a file by using the 
DEFINE/USER_MODE command. 


The VMS card reader driver performs the following error recovery 
operations: 


e If the card reader is offline for 30 seconds, a “device not ready” 
message is sent to the system operator. 


¢ Ifa recoverable card reader failure is detected, a “device not ready” 
message is sent every 30 seconds to the system operator. 
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¢ The current operation is retried every two seconds to test for a changed 
situation, such as the removal of an error condition. 


e The current I/O operation can be canceled at the next timeout without 
the card reader being online. When the card reader comes online, 
device operation resumes automatically. 


When a recoverable card reader failure is detected and an error message 
is displayed on the system operator console, examine the card reader 
indicator lights to determine the reason for the failure. Any errors that 
occur must be fixed manually. The recovery is transparent to the user 
program issuing the I/O request. 


The four categories of card reader failures and their respective recovery 
procedures are as follows: 


e Pick check—The next card cannot be delivered from the input hopper 
to the read mechanism. To recover from this error, remove the next 
card to be read from the input hopper and smooth the leading edge 
(the edge that enters the read mechanism first). Replace the card 
in the input hopper and press the RESET button. The card reader 
operation resumes automatically. If a pick check error occurs again on 
the same card, remove the card from the input hopper and repunch 
it. Place the duplicate card in the input hopper and press the RESET 
button. If the problem persists, either an adjustment is required, or 
nonstandard cards are in the input hopper. 


¢ Stack check—The card just read did not stack properly in the output 
hopper. To recover from this error, remove the last card read from 
the output hopper and examine it. If it is excessively worn or 
mutilated, repunch it. Place either card in the read station of the 
input hopper and press the RESET button. The card reader operation 
resumes automatically. If the stack check error recurs immediately, an 
adjustment is required. 


¢ Hopper check—Either the input hopper is empty or the output hopper 
is full. To recover from this error, examine the input hopper and, 
if empty, either load the next deck of input cards or an end-of-file 
card. If the input hopper is not empty, remove the cards that have 
accumulated in the output hopper and press the RESET button. The 
card reader operation resumes automatically. 


¢ Read check—The last card was read incorrectly. To recover from this 
error, remove the last card from the output hopper and examine it. If 
it is excessively worn, mutilated, or contains punches before column 
0 or after column 80, repunch the card. Place either card in the read 
station of the input hopper and press the RESET button. The card 
reader operation resumes automatically. If the read check error recurs 
immediately, an adjustment is necessary. 
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2.3 Card Reader Driver Device Information 


You can obtain information on card reader characteristics by using the 
Get Device/Volume Information ($GETDVI) system service. See the VMS 
System Services Reference Manual. 


$GETDVI returns card reader characteristics when you specify the item 
codes DVI$_DEVCHAR and DVI$_DEVDEPEND. Tables 2—1 and 2-2 
list these characteristics. The $DEVDEF macro defines the device- 
independent characteristics; the $CRDEF macro defines the device- 
dependent characteristics. 


DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and device 
class names, which are defined by the $DCDEF macro. The device class 
for card readers is DC$_CARD. The device type for the CR11 is DT$_CR11. 
DVI$_DEVBUFSIZ returns the buffer size. The default buffer size to be 
used for all card reader devices is 80 bytes. 
Table 2-1 Card Reader Device-Independent Characteristics 
Characteristic’ Meaning 

Dynamic Bit (Conditionally Set) 


DEV$M_AVL Device is online and available 


Static Bits (Always Set) 
DEV$M_IDV Device is capable of input 
DEV$M_REC Device is record-oriented 


‘Defined by the $DEVDEF macro. 


Table 2-2 Device-Dependent Characteristics for Card Readers 


Value’ Meaning 


CR$V_TMODE _ Specifies the translation mode for nonbinary, nonpacked Hollerith 
CR$S_TMODE data transfers.2 Possible values are: 


CR$K_T026 __—‘ Translate according to 026 punch code 
CR$K_T029 __— Translate according to 029 punch code 


'Defined by the $CRDEF macro. 


?Section 2.2.1.2 describes the set translation mode punch code. 





2.4 Card Reader Function Codes 


The VMS card reader can perform logical, virtual, and physical I/O 
functions. Table 2—3 lists these functions and their function codes. These 
functions are described in more detail in the sections that follow. 
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Read 
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Table 2-3 Card Reader I/O Functions 


Function Code and Function 
Arguments Type' Modifiers Function 
1IO$ READLBLK P1,P2 L lIO$¢M_BINARY Read logical block. 
lIO$M_PACKED 
lO$_ READVBLK P1,P2 V IO$M_BINARY Read virtual block. 
IO$M_PACKED 
lO$ READPBLK P1,P2 P IO$M_BINARY Read physical block. 
IO$M_PACKED 
lO$_ SENSEMODE L Sense the card reader 
characteristics and return 
them in the 1/O status 
block. 
lO$ SETMODE P1 ie Set card reader 


characteristics for 
subsequent operations. 
lO$_ SETCHAR P1 P Set card reader 
characteristics for 
subsequent operations. 


'V = virtual; L = logical; P = physical 


Read is a function that reads data from the next card in the card reader 
input hopper into the designated memory buffer in the specified format. 
Only one card is read each time a read function is specified. 


The VMS operating system provides the following read function codes: 
¢ JO$_READVBLK—Read virtual block 

¢ I0$ READLBLK—Read logical block 

¢ JO$ READPBLK—Read physical block 


The following function-dependent arguments are used with these codes: 


e P1—the starting virtual address of the buffer that is to receive the 
data 


e P2—The number of bytes that are to be read in the specified format 


The read binary function modifier (IO$M_BINARY) and the read packed 
Hollerith function modifier (IO$M_PACKED) can be used with all read 
functions. If IO$M_BINARY is specified, successive columns of 

data are stored in sequential word locations of the input buffer. If 
IO$M_PACKED is specified, successive columns of data are packed and 
stored in sequential byte locations of the input buffer. If neither of these 
function modifiers is specified, successive columns of data are translated 
in the current mode (026 or 029) and are stored in sequential bytes of the 
input buffer. Figure 2~2 shows how data is stored by IO$M_BINARY and 
IO$M_PACKED. 


2.4.2 


2.4.3 


Sense Mode 


Set Mode 
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Figure 2-2 Binary and Packed Column Storage 


Binary Column (IO$M_BINARY): 
15 12 11 0 


po +) 2 110123456789 


*Bits 12-15 are 0. 
Packed Column (IO$M_PACKED): 


ra 3.2 0 


*n = 0 if no punches in rows 1-7. 
= 1 if apunch in row 1. 
= 2 if a punch in row 2. 


= 7 if a punch in row 7. 
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Regardless of the byte count specified by the P2 argument, a maximum 
of 160 bytes of data for binary read operations and 80 bytes of data for 
nonbinary read operations (IO$M_PACKED, or 026 or 029 modes) are 
transferred to the input buffer. If P2 specifies less than the maximum 
quantity for the respective mode, only the number of bytes specified are 
transferred; any remaining buffer locations are not filled with data. 


Sense mode is a function that senses the current device-dependent card 
reader characteristics and returns them in the second longword of the I/O 
status block (see Table 2~2). No device- or function-dependent arguments 
are used with IO$_SENSEMODE. 


Set mode operations affect the operation and characteristics of the 
associated card reader device. The VMS operating system defines the 
following types of set mode functions: 


e Set mode 


e Set characteristic 
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Set Mode 


The set mode function affects the characteristics of the associated card 
reader. Set mode is a logical I/O function and requires the access privilege 
necessary to perform logical I/O. The following function code is provided. 


¢ I0$_SETMODE 


This function takes the following device- or function-dependent argument: 


e P1—tThe address of a characteristics buffer 


Figure 2—3 shows the quadword set mode characteristics buffer. 


Figure 2-3 Set Mode Characteristics Buffer 


31 16 15 0 


Card Reader Characteristics 
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Table 2—4 lists the card reader characteristics and their meanings. The 
$CRDEF macro defines the characteristics values. Table 2—5 lists the 026 
and 029 card reader codes. 


Table 2-4 Set Mode and Set Characteristic Card Reader Characteristics 


Value’ Meaning 


CR$V_TMODE _ Specifies the translation mode for nonbinary, nonpacked Hollerith 
CR$S_TMODE _ data transfers. Possible values are: 


CR$K_T026 Translate according to 026 punch code 
CR$K_T029 Translate according to 029 punch code 


‘If neither the 026 nor 029 mode is specified, the default mode can be set by the 
SET CARD_READER command. 


Table 2—5 Card Reader Codes 


Character ASClls DEC029 DEC026 
{ 173 120 120 

} 175 110 110 
SPACE 40 NONE NONE 


(continued on next page) 
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Table 2—5 (Cont.) Card Reader Codes 


Character ASCIl, DEC029 DEC026 
! 41 1182 1287 
" 42 87 085 
= 43 83 086 
$ 44 1183 1183 
% 45 084 087 
& 46 12 1187 
47 85 86 
( 50 1285 084 
) 51 1185 1284 
- 52 1184 1184 
+ 53 1286 12 
; 54 083 083 
- 55 14 11 
; 56 1283 1283 
/ 57 01 01 
0 60 0 0 
1 61 1 1 
2 62 2 2 
3 63 3 3 
4 64 4 4 
5 65 5 5 
6 66 6 6 
7 67 7 7 
8 70 8 8 
9 71 9 9 
72 82 1182 
73 1186 082 
< 74 1284 1286 
= 75 86 83 
> 76 086 1186 
? 77 087 1282 
@ 100 8 4 84 
A 101 12 1 12 1 
B 102 122 122 
C 103 123 123 
D 104 124 124 


(continued on next page) 
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Table 2-5 (Cont.) Card Reader Codes 


Character ASCIl, DEC029 DEC026 
E 105 125 125 
F 106 126 126 
G 107 127 127 
H 110 128 128 

| 114 129 129 
J 112 1114 111 
K 113 112 112 
L 114 113 a ie 
M 115 114 114 
N 116 115 115 
O 117 116 116 
P 120 ued 11-7 
Q 121 118 118 
R 122 119 119 
S 123 02 02 

al; 124 03 03 

U 125 04 04 

V 126 05 05 
W 127 06 06 

X 130 07 07 

¥ 131 08 08 

Z 132 09 09 

[ 133 1282 1185 
\ 134 1187 87 

] 135 082 1285 
tor” 136 1287 85 
<— OF __ 137 085 82 


Application programs that change specific card reader characteristics 
should first use the IO$_SENSEMODE function to read the current 
characteristics, modify them, and then use the set mode function to write 
back the results. Failure to follow this sequence results in clearing any 
previously set characteristic. 


2.4.3.2 Set Characteristic 
The set characteristic function also affects the characteristics of the 
associated card reader device. Set characteristic is a physical I/O function, 
and requires the access privilege necessary to perform physical I/O 
functions. The following function code is provided: 


e I0$_SETCHAR 
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This function takes the following device- or function-dependent argument: 


e¢  P1—tThe address of a characteristics buffer 


Figure 2—4 shows the set characteristic characteristics buffer. 


Figure 2-4 Set Characteristic Buffer 


31 16 15 8 7 0 


[etersco (|e 
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The device type value is DT$_CR11. The device class value is DC$_CARD. 
Table 2—4 lists the card reader characteristics for the Set Characteristic 
function. _ 


The I/O status block (IOSB) format for QIO functions on the card reader 
is shown in Figure 2-5. Appendix A lists the status returns for these 
functions. (The VMS System Messages and Recovery Procedures Reference 
Manual provides explanations and suggested user actions for these 
returns.) Table 2—2 lists the device-dependent data returned in the second 
longword. The IO$_SENSEMODE function can be used to obtain this 
data. 


Figure 2-5 IOSB Contents 


31 16 15 0 





Device—Dependent Data 
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3 Disk Drivers 


This chapter describes the use of VMS disk drivers. These drivers support 
the devices listed in Table 3-1, 


All disk drivers support Files—11 On-Disk Structure Level 1 and Level 
2 file structures. Access to these file structures is through the DCL 
commands INITIALIZE and MOUNT, followed by the VMS RMS calls 
described in the VMS Record Management Services Manual. Files in 
RT-—11 format can be read or written with the file exchange facility 
EXCHANGE. 





3.1 Supported Disk Devices and Controllers 


The following sections provide greater detail about the disk devices listed 
in Table 3-1. To obtain additional information about a device, use 

the DCL command SHOW DEVICE with the /FULL qualifier, the Get 
Device/Volume Information ($GETDVI) system service (from a program), 
or the F$GETDVI lexical function (in a command line or command 
procedure). Section 3.3 lists the information on disk devices returned 

by $GETDVI. 


Table 3-1 Supported Disk Devices 


Disk Capacity 
Device Code Type DSA (Logical Blocks/Drive) 
RA6O DJ Removable Yes 400,176 
RA70 DU Fixed Yes 547,041 
RA80 DU Fixed Yes 236,964 
RA81 DU Fixed Yes 891,072 
RA82 DU Fixed Yes 1,216,665 
RASO DU Fixed Yes 2,343,750 
RBO2 DQ Cartridge No 20,480 
RB80 DQ Fixed No 242,606 
RC25 DA Fixed, Yes' 102,400? 
Cartridge 
RD32 DU Fixed Yes! 83,204 
RD51 DU Fixed Yes'*® 21,600 


"Incompatible with the UDA50, KDA50, KDB50, HSC40, HSC50, and HSC70 disk controllers. 
251,200 fixed; 51,200 cartridge. 


3The RD series of disk drives conforms to DSA when used with the RQDX series of controllers. 
RD-series disk drives do not conform to DSA when used on a VAXstation 2000. 


(continued on next page) 
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Table 3-1 (Cont.) Supported Disk Devices 


Disk Capacity 
Device Code Type DSA (Logical Blocks/Drive) 
RD52 DU Fixed Yes'* 60,480 
RD53 DU Fixed Yes'* 138,672 
RD54 DU Fixed Yes'* 311,200 
RF30 DI Fixed Yes' 292,968 
RF71 DI Fixed Yes' 781,250 
RLO2 DL Cartridge No 20,480 
RMO03 DR Removable No 131,680 
RMO05 DR Removable No 500,384 
RM80 DR Fixed No 242,606 
RPO5 DB Removable No 171,798 
RPO6 DB Removable No 340,670 
RPO7 DR Fixed No 1,008,000 
RKO6 DM Cartridge No 27,126 
RKO7 DM Cartridge No 53,790 
RRD40 DUor Optical Yes’ 1,669,400 
DkK* Optical No 1,669,400 
RRD50 = =DU Optical Yes’ 1,669,400 
RX01 DX Flexible No 494 
RX02 DY Flexible No 494° 
988 ° 
RX23 DU Flexible Yes’ 2,734 
RX33 DU Flexible Yes' 2,400 
RX50 DU Flexible Yes’ 800 
RZ22 DK Fixed No 101,563 
RZ23 DK Fixed No 203,125 
RZ55 DK Fixed No 742,188 
TU58’ DD Cartridge No 512 


‘Incompatible with the UDA50, KDA50, KDB50, HSC40, HSC50, and HSC70 disk controllers. 


38The RD series of disk drives conforms to DSA when used with the RQDX series of controllers. 
RD-series disk drives do not conform to DSA when used on a VAXstation 2000. 


4SCSI interface RRD40 compact disc drive. 
5Single density (See Section 3.3). 
SDouble density (See Section 3.3). 


7A magnetic tape device, the TU58 operationally resembles a disk device. See Section 3.1.24 
for a description of the TU58 in disk terms. 
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3.1.1 UDA50 UNIBUS Disk Adapter 


The UDA50 UNIBUS Disk Adapter (UDA50) is a microprocessor-based 
disk controller for mass storage devices that implement the DIGITAL 
Storage Architecture (DSA); for more information on the DSA, see 
Section 3.2.3. 


The UDASO is used to connect any combination of four RA60, RA80, and 
RA81 disk drives to the UNIBUS. Two UDAS50 controllers can be attached 
to a single UNIBUS for a maximum of eight disk drives per UNIBUS. 
On the VAX-11/780 processor, the VMS operating system supports one 
UDAS5O on the first UNIBUS, which can accommodate certain other 
options. Adding a second UDA50 requires a second UNIBUS. With the 
exception of the first UNIBUS, a maximum of two UDA50s per UNIBUS 
are supported. If two UDA50s are on a UNIBUS, no other options can 

be placed on that UNIBUS. The VAX-11/730 processor supports only one 
UDA5O per UNIBUS. 


The UDA5O, in implementing DSA, takes over the control of the physical 
disk unit. The VMS operating system processes request virtual or logical 
I/O on disks controlled by the UDA50. The VMS operating system maps 
virtual block addresses into logical block addresses. The UDA50 then 

resolves logical block addresses into physical block addresses on the disk. 


The UDA50 corrects bad blocks on the disk by requesting that the disk 
class driver revector a failing physical block to another, error-free 
physical block on the disk; the logical block number is not changed (see 
Section 3.2.10.1). Any bad blocks that might exist on a disk attached to a 
UDASO are transparent to the VMS operating system, which does logical 
or virtual I/O to such a disk. The UDA50 also corrects most data errors. 


3.1.2 | KDA50 Disk Controller 


The KDA50 disk controller is a two-module disk controller that allows the 
RA-series DSA disk drives to be attached to Q-bus systems. The KDA50 
performs the same functions as the UDA50 (see Section 3.1.1). 


3.1.3. KDB50 Disk Controller 


The KDB50 disk controller is a two-module disk controller that allows the 
RA-series DSA disk drives to be attached to BI bus systems, such as the 
VAX 8200 processor. The KDB50 performs the same functions as the 
UDASO (see Section 3.1.1). 


3.1.4 HSC-Series Controllers 


The HSC series of intelligent disk controllers consists of the HSC40, 

HSC50, and the HSC70. HSC controllers are high-speed, high-availability 
controllers for mass storage devices that implement the DIGITAL Storage 
Architecture (DSA); for more information about the DSA, see Section 3.2.3. 
An HSC controller is connected to a processor by a Computer Interconnect 
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(CI). The VMS operating system supports the use of the HSC40, HSC50, 
HSC70 in controlling the RA family of disks. 


The HSC40 can support up to 12 SDI disks from the SA or RA families 
of disk drives or a combination of up to 12 SDI disk drives and TA-series 
tape drives. 


The HSC70 can support up to 32 SDI disks from the SA or RA families of 
disk drives or a combination of SDI disk drives and TA-series tape drives. 


HSC controllers, in implementing DSA, take over the control of the 
physical disk unit. VMS operating system processes request virtual or 
logical I/O on disks controlled by the HSC controller. The VMS operating 
system maps virtual block addresses into logical block addresses. The 
HSC controller then resolves logical block addresses into physical block 
addresses on the disk. 


HSC controllers correct bad blocks on the disk by revectoring a failing 
physical block to another, error-free physical block on the disk; the logical 
block number is not changed. The VMS operating system, which performs 
logical or virtual I/O to such a disk, does not recognize that any bad blocks 
might exist on a disk attached to an HSC controller. HSC controllers also 
correct most data errors. 


The HSC series of controllers provides access to disks despite most 
hardware failures. Use of an HSC controller permits two or more 
processors to access files on the same disk. 


Note: Only one system should have write access to a Files-11 On-Disk 
Structure Level 1 disk or to a foreign-mounted disk; all other 
systems should only have read access to the disk. For Files-11 
On-Disk Structure Level 2 volumes, the VMS operating system 
enables read/write access to all nodes that are members of the 
same VAXcluster. 


HSC-series controllers allow you to add or subtract disks from the device 
configuration without rebooting the system. 


3.1.5 Sli Integral Adapter 


The SII integral adapter on the MicroVAX 3300/3400 provides access 
through the DIGITAL Small Storage Interconnect (DSSI) bus to a 
maximum of seven storage devices. 


The term dual-host refers to pairs of CPUs connected to a bus. In dual- 
host configurations of pairs of MicroVAX 3300/3400 CPUs, the DSSI bus 
must be connected between the SII integral adapters present on both 
CPUs. 


A maximum of six devices can be connected to the SII integral adapter in 
dual-host configurations. 


3.1.6 


3.1.7 


3.1.8 


3.1.9 


KFQSA Adapter 


Disk Drivers 
3.1 Supported Disk Devices and Controllers 


The KFQSA adapter allows a maximum of seven storage devices for use 
on Q-bus systems. 


In dual-host configurations of pairs of MicroVAX 3800/3900 CPUs, the 
DSSI bus must be connected between KFQSA adapters present on both 
CPUs. 


A maximum of six devices can be connected to the KFQSA adapter in 
dual-host configurations. 


RQDX3 Controller 


RA60 Disk 


The RQDX3 is a Q-bus controller used with the RD series of Winchester- 
type disk drives and the RX33 and RX50 flexible diskette drives. 


RA70 and RA90O Disk Drives 


The RA70 is a 5.25-inch 280-megabyte (MB) high-performance DSA disk 
drive that uses thin-film media. It has an average access time of 27.0 
milliseconds (ms) and average seek time of 19.5 ms. The RA70 uses the 
Standard Disk Interconnect (SDI) and the KDA50 controller, and can be 
dual-ported. 


The RA90 is a 1.2-gigabyte disk drive designed with thin-film heads and 
9-inch thin-film media with an average seek time of 18.5 ms. The RA90 
conforms to DSA and uses the SDI. Both the RA70 and RA90 disk drives 
can be connected to medium-sized systems with the HSC-series controllers, 
KDB50, or UDAS50 controllers. 


The RA60 device uses high-capacity, removable media that provides 205 
MB of usable storage (7.5 million bits of data per square inch) with 
transfer rates of 1.9 MB per second (burst) and 950 KB per second 
(sustained). The RA60 belongs to the DIGITAL Storage Architecture 
(DSA) family of disk devices (see Section 3.2.3). It is connected to either 
a UNIBUS Disk Adapter (UDA50) or an HSC50 controller. Up to four 
disk drives can be connected to each UDA50. Up to 24 disk drives can be 
connected to each HSC50. 


3.1.10 RA80/RB80/RM80 and RA81 Fixed-Media Disks 


The R80 disk drive is a high-capacity, moving-head disk whose 
nonremovable media consists of 14 data surfaces. Depending on how it 
is connected to the system, the R80 is identified internally as an RA80, 
RB80, or RM80, as follows: 


¢ RA80—An R80 connected to the system through a UNIBUS disk 
adapter (UDA50) or an HSC50 controller. Up to four disk drives can 
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be connected to each UDA50. Up to 24 disk drives can be connected to 
each HSC50. 


¢ RB80—An R80 connected to the system through an RB7380 controller 
on a VAX 11/730 processor. Of the maximum of four drives that can be 
connected to an RB730 controller, only one can be an RB80. 


¢ RM80—An R80 connected to the system through a MASSBUS adapter 
(MBA). Up to eight disk drives can be connected to each MBA. 


The RA81 is a high-capacity disk drive with nonremovable media that can 
hold more than 890,000 blocks of data. This translates into more than 
455 MB per spindle. The RA81 is connected to a UDA50 or an HSC50 
controller. Up to four disk drives can be connected to each UDA50. Up to 
24 drives can be connected to each HSC50. 


The RA80 and RA81 belong to the DIGITAL Storage Architecture (DSA) 
family of disk devices (see Section 3.2.3). 


3.1.11 RBO2 and RLO2 Cartridge Disk 


3.1.12 RC25 Disk 


3.1.13 RD-Series Disks 
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The RLO2 cartridge disk is a removable, random-access mass storage 
device with two data surfaces. The RL02 is connected to the system 

by an RL11 controller that interfaces with the UNIBUS adapter. Up 

to four RLO2 disk drives can be connected to each RL11 controller. For 
physical I/O transfers, the track, sector, and cylinder parameters describe 
a physical 256-byte RLO2 sector (see Section 3.4). 


When the RLO02 is connected to an RB730 controller on a VAX-11/730 
processor, it is identified internally as an RBO2 disk drive. Disk geometry 
is unchanged and RLO2 disk packs can be exchanged between drives on 
different controllers. Up to four drives can be connected to the RB730 
controller. 


The RC25 disk is a self-contained, Winchester-type, mass storage device 
that consists of a disk adapter module, a disk drive, and an integrated 
disk controller. The drive contains two 8-inch, double-sided disks. One of 
the disks (RCF25) is a sealed, nonremovable, fixed-media disk. The other 
disk is a removable cartridge disk that is sealed until it is loaded into the 
disk drive. The disks share a common drive spindle, and together they 
provide 52 million bytes of storage. Adapter modules interface the RC25 
with either a UNIBUS system or a Q-bus system. 


The RD53 and RD54 are 5.25-inch, full-height, Winchester-type drives 
with average access time of 38 ms and a data transfer rate of 0.625 MB 
per second. The RD53 and RD54 have a formatted capacity of 71 MB and 
159 MB, respectively. When used with the RQDX8 controller, the RD53 
and RD54 are DSA disks. 


3.1.14 


3.1.15 


3.1.16 


3.1.17 


3.1.18 
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See Section 3.2.11 for information about using RD series disks on the 
VAXstation 2000. 


RF-Series Disks 


The RF series of Winchester-type disk drives consists of the RF30 and 
the RF71. The RF30 is a 150-MB, 5.25-inch, half-height disk drive 
while the RF71 is a 400-MB full-height disk drive. The RF30 and RF71 
include an embedded controller for multihost access and a Mass Storage 
Communications Protocol (MSCP) server. The RF71 has a peak data 
transfer rate of 1.5 MB per second with average seek and access time of 
21 ms and 29 ms, respectively. 


Both the RF380 and RF71 disks use DIGITAL Storage System Interconnect 
(DSSI) bus and host adapters. 


RKO6 and RKO7 Cartridge Disks 


The RKO6 cartridge disk is a removable, random-access, bulk storage 
device with three data surfaces. The RKO7 cartridge disk is a double- 
density RKO6. The RKO06 and RKO7 are connected to the system by an 
RK611 controller that interfaces to the UNIBUS adapter. Up to eight disk 
drives can be connected to each RK611. 


RM03 and RM05 Pack Disks 


The RM03 and RM05 pack disks are removable, moving-head disks that 
consist of five data surfaces for the RM03 and 19 data surfaces for the 
RMO05. These disks are connected to the system by a MASSBUS adapter 
(MBA). Up to eight disk drives can be connected to each MBA. 


RPO5 and RP0O6 Disk 


The RPO5 and RPO6 removable disks consist of 19 data surfaces and a 
moving read/write head. The RP06 removable disk has approximately 
twice the capacity of the RP05. These disks are connected to the system 
by an MBA. Up to eight disk drives can be connected to each MBA. 


RP0O7 Fixed Media Disk 


The RPO7 is a 516-MB, fixed media disk drive that attaches to the 
MASSBUS of the VAX—11/780 system. The RPO7 transfers data at 1.3 
million bytes per second or as an option at a peak rate of 2.2 million 
bytes per second. The nine platters rotate at 3600 rpm and their data 
is accessed at an average speed of 31.3 milliseconds. These disks are 
connected to the system by an MBA. Up to eight disk drives can be 
connected to each MBA. 
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3.1.19 RRD40 and RRD50 Read-Only Memory (CDROM) 


The RRD40 and RRD50 are Compact Disc Read-Only Memory (CDROM) 
devices that use replicated media with a formatted capacity of 
approximately 600 MB. 


The RRD40 is a 5.25-inch half-height, front-loading table-top or embedded 
device that attaches to the system using either the Small Computer 
System Interface (SCSD or Q-bus interface. 


The RRD50 is a 5.25-inch, top-loading table-top device that attaches to the 
system using a Q-bus interface. 


The RRD40 has an average access time of 0.5 seconds while the average 
access time for the RRD50 is 1.5 seconds. Both the RRD40 and RRD50 
have a data transfer rate of 150 KB per second. 


The media for the RRD40 and the RRD50 are removable 4.7-inch 

(120 mm) compact disks. However, the media for the RRD40 are enclosed 
in protective self-loading carriers. The RRD40 with a SCSI interface 

is also available as an embedded unit. The RRD40 and RRD50 Q-bus 
subsystems are standard disk MSCP devices. 


3.1.20 RX01 Console Disk 


The RX01 disk uses a diskette. The disk is connected to the LSI console 
on the VAX-—11/780, which the driver accesses using the MTPR and MFPR 
privileged instructions. 


For logical and virtual block I/O operations, data is accessed with one block 
resolution (four sectors). The sector numbers are interleaved to expedite 
data transfers. Section 3.2.9 describes sector interleaving in greater detail. 


For physical block I/O operations, the track, sector, and cylinder 
parameters describe a physical, 128-byte RX01 sector (see Figure 3-1 
and Section 3.4). Note that the driver does not apply track-to-track skew, 
cylinder offset, or sector interleaving to this physical medium address. 


3.1.21 RX02 Disk 


The RX02 disk is a mass storage device that uses removable diskettes. 
The RX02 supports existing single-density, RX01-compatible diskettes. A 
double-density mode allows diskettes to be recorded at twice the linear 
density. An entire diskette must be formatted in either single or double 
density. Mixed mode diskettes are not allowed. 


The RX02 is connected to the system by an RX211 controller that 
interfaces with the UNIBUS adapter. Up to two disk drives can be 
controlled by each RX211. 
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Figure 3-1 Disk Physical Address 


31 16 15 8 7 0 


P3: Cylinder Track | Sector 


(Except RX01 and RX02) 


31 16 15 0 


(RX01 and RX02 Only) 


ZK-0652—GE 


For logical and virtual block I/O operations, data is accessed with 
single block resolution (four single-density sectors or two double-density 
sectors). The sector numbers are interleaved to expedite data transfers. 
Section 3.2.9 describes this feature in greater detail. 


For physical block I/O operations, the track and sector parameters shown 
in Figure 3-1 describe a physical sector (128 bytes in single density; 256 
bytes in double density). The driver does not apply track-to-track skew, 
cylinder offset, or sector interleaving to the physical medium address. 


3.1.22 RX-Series Drives 
The following sections describe the RX family of flexible diskette drives. 


3.1.22.1 RX23 
The RX23 device is a one-inch high, flexible diskette drive that uses 
3.5-inch microfloppy diskettes. The RX23 drive can access standard- 
and high-density media. The following table summarizes capacities for 
standard- and high-density media. 
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Density Unformatted Formatted 
Standard 1.0 MB 700 KB 
High 2.0 MB 1.4 MB 


The RX23 is backwardly compatible in that it can read 1-MB media. It 
can also read and write 2.0-MB double-sided, high-density (135 tracks per 
inch) media. 


The RX23 communicates with the controller using the ST506 fixed disk 
interconnect (FDI). 


3.1.22.2 RX33 


The RX33 is a 1.2 MB, 5.25-inch, half-height diskette drive. The RX33 

can record in either standard- or high-density mode. High-density mode 
provides 1.2 MB of storage using 96 tracks per inch using double-sided, 
high-density diskettes. 


In standard-density mode, the RX33 drive is read- and write-compatible 
with single-sided, standard-density RX50 diskettes. 


3.1.22.3  RX50 


3.1.23 RZ-Series Disks 


The RX50 dual diskette drive stores data in fixed-length blocks on 
5.25-inch 0.8-MB, flexible diskettes using preformatted headers. The RX50 
can accommodate two diskettes simultaneously. 


The RZ series of Winchester-type disk drives consists of the RZ22, RZ23, 
and the RZ55. The RZ22 and RZ23 are 3.5-inch, half-height SCSI drives 
with an average seek rate of 33 ms and an average data transfer rate of 
1.25 MB per second. The RZ22 and RZ23 have a capacity of 52 MB and 
104 MB, respectively. 


The RZ55 is a 332-MB, 5.25-inch, full-height SCSI drive with an average 
access rate of 24 ms. 


3.1.24 TU58 Magnetic Tape (DECtape Il) 
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The TU58 is a random-access, mass storage magnetic tape device capable 
of reading and writing 256K bytes per drive of data on block-addressable, 
preformatted cartridges at 800 bits per inch. Unlike conventional magnetic 
tape systems, which store information at variable positions on the tape, 
the TU58 stores information at fixed positions on the tape, as do magnetic 
disk or floppy disk devices. Thus, blocks of data can be placed on tape 

in a random fashion, without disturbing previously recorded data. In its 
physical geometry, the tape is conceptually viewed as having one cylinder, 
four tracks per cylinder, and 128 sectors per track. Each sector contains 
one 512-byte block. 


The TU58 uses two vectors. NUMVEC=2 is required on the CONNECT 
command when specifying SYSGEN parameters. 


3.2 


3.2.1 


Driver Features 
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The TU58 interfaces with the UNIBUS adapter through a DL11-series 
interface device. Both the TU58 and the DL11 should be set to 9600 
baud. (Because the TU58 is attached to a DL11, the user cannot directly 
access the TU58 registers if the TU58 is on the UNIBUS.) The DIGITAL 
Terminals and Communications Handbook provides additional information 
on the DL11. The TU58, which has its own controller, can access either 
one or two tape drives. 





VMS disk drivers provide the following features: 


¢ Multiple controllers of the same type (except RB730), for example, 
more than one MBA or RK611 can be used on the system 


¢ Multiple disk drives per controller (The exact number depends on the 
controller.) 


¢ Different types of disk drives on a single controller 
e Static dual porting (MBA drives only) 
¢ Overlapped seeks (except RLO2, RX01, RX02, and TU58) 


¢ Data checks on a per-request, per-file, or per-volume basis (except 
RX01 and RX02) 


¢ Full recovery from power failure for online disk drives with volumes 
mounted 


e Extensive error recovery algorithms, such as error code correction and 
offset (except RBO2, RLO2, RX01, RX02, and TU58); for DSA disks, 
these algorithms are implemented in the controller 


¢ Dynamic, as well as static, bad block handling 


e Logging of device errors in a file that can be displayed by field service 
personnel or customer personnel 


¢ Online diagnostic support for drive level diagnostics 


¢ Multiple-block, noncontiguous, virtual I/O operations at the driver 
level 


¢ Logical-to-physical sector translation (RX01 and RX02 only) 


The following sections describe the data check, overlapped seek, error 
recovery, and logical-to-physical translation features in greater detail. 


Dual-Pathed Disks 


A dual-pathed disk is a dual-ported disk that is accessible to all 
the CPUs in the VAXcluster, not just to the CPUs that are connected 
physically to the disk. Dual-pathed disks can be any of the following: 


¢ Dual-ported MASSBUS disks 
¢ Dual-ported HSC disks 
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¢ Dual-pathed DSA disks on local UDA50, KDA50, and KDB50 
controllers 


¢ Dual-ported RF-series disks 


The term dual-pathed refers to the two paths through which clustered 
CPUs can access a disk to which they are not directly connected. If one 
path fails, the disk is accessed over the other path. (Note that with a 
dual-ported MASSBUS disk, a CPU directly connected to the disk always 
accesses it locally.) 


3.2.2 Dual Porting MASSBUS Disks 


3.2.2.1 Port 
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The VMS MASSBUS disk drivers, DBDRIVER and DRDRIVER, support 
static dual porting. Dual porting allows two MASSBUS controllers to 
access the same disk drive. Figure 3-2 shows this configuration. The 
RP05, RP06, RPO7, RM03, RM05, and RM8O0 disk drives can be ordered, or 
upgraded in the field, with the MASSBUS dual port option. 


Figure 3-2 Dual-Ported Disk Drives 






Controller Controller 


ZK-0650-GE 


Selection and Access Modes 

The port select switches, on each disk drive, select the ports from which 
the drive can be accessed. A drive can be in one of the following access 
modes: 


¢ Locked on Port A—The drive is in a single-port mode (Port A). It does 
not respond to any request on Port B. 


¢ Locked on Port B—The drive is in a single-port mode (Port B). It does 
not respond to any request on Port A. 


Disk Drivers 
3.2 Driver Features 


e Programmable A/B—The drive is capable of responding to requests on 
either Port A or Port B. In this mode, the drive is always in one of the 
following states: 


— The drive is connected and responding to a request on Port A. It is 
closed to requests on Port B. 


— The drive is connected and responding to a request on Port B. It is 
closed to requests on Port A. 


— The drive is in a neutral state. It is equally available to requests 
on either port on a first-come, first-serve basis. 


The operational condition of the drive cannot be changed with the port 
select switches after the drive becomes ready. To change from one mode to 
another, the drive must be in a nonrotating condition. After the new mode 
selection has been made, the drive must be restarted. 


If a drive is in the neutral state and a disk controller either reads or 
writes to a drive register, the drive immediately connects a port to the 
requesting controller. For read operations, the drive remains connected 
for the duration of the operation. For write operations, the drive remains 
connected until a release command is issued by the device driver or a 
one second timeout occurs. After the connected port is released from 

its controller, the drive checks the other port’s request flag to determine 
whether there has been a request on that port. If no request is pending, 
the drive returns to the neutral state. 


3.2.2.2 Disk Use and Restrictions 


If the volume is mounted foreign, read/write operations can be performed 
at both ports provided the user maintains control of where information is 
stored on the disk. 


The Autoconfigure Utility currently may not be able to locate the nonactive 
port. For example, if a dual-ported disk drive is connected and responding 
at Port A, the CPU attached to Port B might not be able to find Port B 
with the Autoconfigure Utility. If this problem occurs, execute the 
AUTOCONFIGURE ALL/LOG command after the system is running. 


3.2.2.3 Restriction on Dual-Ported Non-DSA Disks in a VAXcluster 


Note: 


Do not use SYSGEN to AUTOCONFIGURE or CONFIGURE a dual- 
ported, non-DSA disk that is already available on the system through 
use of an MSCP server. Establishing a local connection to the disk when 
a remote path is already known creates two uncoordinated paths to the 
same disk. Use of these two paths may corrupt files and data on any 
volume mounted on the drive. 


If the disk is not dual-ported or is never served by an MSCP server 
on the remote host, this restriction does not apply. 


In a VAXcluster, dual-ported non-DSA disks (MASSBUS or UNIBUS) can 
be connected between two nodes of the cluster. These disks can also be 
made available to the rest of the cluster using the MSCP server on either 
or both of the hosts to which a disk is connected. 
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If the local path to the disk is not found during the bootstrap, then the 
MSCP server path from the other host will be the only available access 
to the drive. The local path will not be found during a boot if any of the 
following conditions exist: 


¢ The port select switch for the drive is not enabled for this host. 
¢ The disk, cable, or adapter hardware for the local path is broken. 


¢ There is sufficient activity on the other port to hide the existence of 
the port. 


e The system is booted in such a way that the 
SYSGEN AUTOCONFIGURE ALL command in the 
SYS$SYSTEM:STARTUP.COM procedure was not executed. 


Use of the disk is still possible through the MSCP server path. 


After the configuration of the disk has reached this state, it is important 
not to add the local path back into the system I/O database. Because the 
VMS operating system does not provide an automatic method for adding 
this local path, the only possible way that you can add this local path 

is to use the Sysgen Utility (SYSGEN) qualifiers AUTOCONFIGURE or 
CONFIGURE to configure the device. SYSGEN is currently not able to 
detect the presence of the disk’s MSCP path, and will incorrectly build a 
second set of data structures to describe it. Subsequent events could lead 
to incompatible and uncoordinated file operations, which might corrupt the 
volume. 


To recover the local path to the disk, it is necessary to reboot the system 
connected to that local path. 


See the VMS VAXcluster Manual for additional information on dual-ported 
disk operation. 


3.2.3 Dual-Pathed DSA Disks 
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Note: 


A dual-ported DSA disk can be failed over between the two CPUs that 
serve it to the VAXcluster under the following conditions: (1) the same 
disk controller letter and allocation class are specified on both CPUs and 
(2) both CPUs are running the MSCP server. 


Failure to observe these requirements can endanger data integrity. 


However, because a DSA disk can be online to only one controller at a 
time, only one of the CPUs can use its local connection to the disk. The 
second CPU accesses the disk through the MSCP server. If the CPU 
that is currently serving the disk fails, the other CPU detects the failure 
and fails the disk over to its local connection. The disk is thereby made 
available to the VAXcluster once more. 


A dual-ported DSA disk may not be used as a system disk. 


3.2.4 


3.2.5 


3.2.6 


Data Check 


Note: 
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Dual-Porting HSC Disks 


By design, HSC disks are cluster accessible. Therefore, if they are dual 
ported, they are automatically dual pathed. CI-connected CPUs can access 
a dual-pathed HSC disk by way of a path through either HSC-connected 
device. 


For each dual-ported HSC disk, you can control failover to a specific port 
using the port select buttons on the front of each drive. By pressing either 
port select button (A or B) on a particular drive, you can cause the device 
fail over to the specified port. 


With the port select button, you can select alternate ports to balance the 
disk controller workload between two HSC subsystems. For example, you 
could set half of your disks to use port A and set the other half to 

use port B. 


The port select buttons also allow you to fail over all the disks to an 
alternate port manually when you anticipate the shutdown of one of the 
HSC subsystems. 


Dual-Pathed RF-Series Disks 


In a dual-path configuration of pairs of MicroVAX 3300/3400 CPUs or 
pairs of MicroVAX 3800/3900 CPUs using RF-series disks, CPUs have 
concurrent access to any disk on the DSSI bus. A single disk is accessed 
through two paths and can be served to all satellites by either CPU. 


If either CPU fails, satellites can access their disks through the remaining 
CPU. Note that failover occurs in the following situations: (1) when the 
DSSI bus is connected between SII integral adapters on both MicroVAX 
3300/3400 CPUs or (2) when the DSSI bus is connected between the 
KFQSA adapters on pairs of MicroVAX 3300/3400s or pairs of MicroVAX 
3800/3900s. 


The DSSI bus should not be connected between a KFQSA adapter 
on one CPU and an SII integral adapter on another. 


A data check is made after successful completion of a read or write 
operation and, except for the TU58, compares the data in memory with the 
data on disk to make sure they match. 


Disk drivers support data checks at the following levels: 


¢ Per request—You can specify the data check function modifier 
(IO$M_DATACHECK) on a read logical block, write logical block, read 
virtual block, write virtual block, read physical block, or write physical 
block operation. IO$M_DATACHECK is not supported for the RX01 
and RX0O1 drivers. 
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¢ Per volume—You can specify the characteristics “data check all reads” 
and “data check all writes” when the volume is mounted. The VMS 
DCL Dictionary describes volume mounting and dismounting. The 
VMS System Services Reference Manual describes the Mount Volume 
($MOUNT) and Dismount Volume ($DISMOU) system services. 


e Per file—You can specify the file access attributes “data check on read” 
and “data check on write.” File access attributes are specified when 
the file is accessed. Chapter 1 of this manual and the VMS Record 
Management Services Manual describe file access. 


Offset recovery is performed during a data check but Error Code 
Correctable (ECC) correction is not performed (see Section 3.2.8). For 
example, if a read operation is performed and an ECC correction is 
applied, the data check would fail even though the data in memory is 
correct. In this case, the driver returns a status code indicating that the 
operation was successfully completed, but the data check could not be 
performed because of an ECC correction. 


Data checks on read operations are extremely rare, and you can either 
accept the data as is, treat the ECC correction as an error, or accept the 
data but immediately move it to another area on the disk volume. 


A data check operation directed to a TU58 does not compare the data in 
memory with the data on tape. Instead, either a read check or a write 
check operation is performed (see Sections 3.4.1 and 3.4.2). 


3.2./. Overlapped Seeks 


A seek operation involves moving the disk read/write heads to a specific 
place on the disk without any transfer of data. All transfer functions, 
including data checks, are preceded by an implicit seek operation (except 
when the seek is inhibited by the physical I/O function modifier 
IO$M_INHSEEK). Seek operations can be overlapped except on RLO2, 
RX01, RX02, TU58 drives, MicroVAX 2000, VAXstation 2000, or on 
controllers with floppy disks (for example, RQDX3) when the disk is 
executing I/O requests. That is, when one drive performs a seek operation, 
any number of other drives can also perform seek operations. 


During the seek operation, the controller is free to perform transfers 
on other units. Thus, seek operations can also overlap data transfer 
operations. For example, at any one time, seven seeks and one data 
transfer could be in progress on a single controller. 


This overlapping is possible because, unlike I/O transfers, seek operations 
do not require the controller once they are initiated. Therefore, seeks 
are initiated before I/O transfers and other functions that require the 
controller for extended periods. 


All DSA controllers perform extensive seek optimization functions as part 
of their operation; IO$M_INHSEEK has no effect on these controllers. 
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Error recovery in the VMS operating system is aimed at performing 
all possible operations to complete an I/O operation successfully. Error 
recovery operations fall into the following categories: 


e Handling special conditions such as power failure and interrupt 
timeout. 


e Retrying nonfatal controller and drive errors. For DSA and SCSI 
disks, this function is implemented by the controller. 


¢ Applying error correction information (not applicable for RB02, RLO2, 
RX01, RX02, and TU58). For DSA and SCSI disks, error correction is 
implemented by the controller. 


e Offsetting read heads to try to obtain a stronger recorded signal (not 
applicable for RB02, RLO2, RB80, RM80, RX01, RX02, and TU58). For 
DSA and SCSI disks, this function is implemented by the controller. 


The error recovery algorithm uses a combination of these four types of 
error recovery operations to complete an I/O operation. 


Power failure recovery consists of waiting for mounted drives to spin up 
and come online, followed by reexecution of the I/O operation that was in 
progress at the time of the power failure. 


Device timeout is treated as a nonfatal error. The operation that was in 
progress when the timeout occurred is reexecuted up to eight times before 
a timeout error is returned. 


Nonfatal controller/drive errors are executed up to eight times before a 
fatal error is returned. 


All normal error recovery procedures (nonspecial conditions) can be 
inhibited by specifying the inhibit retry function modifier (IO$M_ 
INHRETRY). If any error occurs and this modifier is specified, the virtual, 
logical, or physical I/O operation is immediately terminated, and a failure 
status is returned. This modifier has no effect on power recovery and 
timeout recovery. 


3.2.8.1 Skip Sectoring 


Skip sectoring is a bad block treatment technique implemented on R80 
disk drives (the RB80 and RM80 drives). In each track of 32 sectors, 
one sector is reserved for bad block replacement. Consequently, an R80 
drive has available only 31 sectors per track. The Get Device/Volume 
Information ($GETDVI) system service returns this value. 


You can detect bad blocks when a disk is formatted. Most formatters 
place these blocks in a bad block file. On an R80 drive, the first bad block 
encountered on a track is designated as a skip sector. This is accomplished 
by setting a flag in the sector header on the disk and placing the block in 
the skip sector file. 
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When a skip sector is encountered during a data transfer, it is skipped 
over, and all remaining blocks in the track are shifted by one physical 
block. For example, if block number 10 is a skip sector, and a transfer 
request was made beginning at block 8 for four blocks, then blocks 8, 9, 11, 
and 12 will be transferred. Block 10 will be “skipped.” 


Because skip sectors are implemented at the device driver level, they are 
not visible to you. The device appears to have 31 contiguous sectors per 
track. Sector 32 is not directly addressable, although it is accessed if a 
skip sector is present on the track. 


3.2.9 Logical-to-Physical Translation (RX01 and RX02) 
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Logical block-to-physical sector translation on RX01 and RX02 drives 
adheres to the standard VMS format. For each 512-byte logical block 
selected, the driver reads or writes four 128-byte physical sectors (or 

two 256-byte physical sectors if an RX02 is in double-density mode). 

To minimize rotational latency, the physical sectors are interleaved. 
Interleaving allows the processor time to complete a sector transfer before 
the next sector in the block reaches the read/write heads. To allow for 
track-to-track switch time, the next logical sector that falls on a new track 
is skewed by six sectors. (There is no interleaving or skewing on read 
physical block and write physical block I/O operations.) Logical blocks are 
allocated starting at track 1; track 0 is not used. 


The translation procedure, in more precise terms, is as follows: 


1 Compute an uncorrected medium address using the following 
dimensions: 


Number of sectors per track = 26 
Number of tracks per cylinder = 1 
Number of cylinders per disk = 77 


2 Correct the computed address for interleaving and track-to-track 
skew (in that order) as shown in the following VAX FORTRAN 
statements. ISECT is the sector address and ICYL is the cylinder 
address computed in step 1: 


Interleaving: 


ITEMP = ISECT*2 
IF (ISECT .GT. 12) ITEMP = ITEMP-25 


ISECT = ITEMP 

Skew: 

ISECT = ISECT+(6*ICYL) 
ISECT = MOD (ISECT, 26) 


3 Set the sector number in the range of 1 through 26 as required by the 
hardware: 


ISECT = ISECT+1 
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4 Adjust the cylinder number to cylinder 1 (cylinder 0 is not used): 
ICYL = ICYL+1 


3.2.10 DIGITAL Storage Architecture (DSA) Devices 


The DIGITAL Storage Architecture (DSA) is a collection of specifications 
that cover all aspects of a mass storage product. The specifications are 
grouped into the following general categories: 


e¢ Media format—Describes the structure of sectors on a disk and the 
algorithms for replacing bad blocks 


¢ Drive-to-controller interconnect—Describes the connection between a 
drive and its controller 


¢ Controller-to-host communications—Describes how hosts request 
controllers to transfer data 


Because the VMS operating system supports all DSA disks, it supports all 
controller-to-host aspects of DSA. Some of these disks, such as the RA60, 
RA80, and RA81, use the standard drive-to-controller specifications. Other 
disks, such as the RC25, RD51, RD52, RD53, and RX50, do not. Disk 
systems that use the standard drive-to-controller specifications employ 
the same hardware connections and use the HSC50, KDA50, KDB50, 

and UDAS50 interchangeably. Disk systems that do not use the drive- 
to-controller specifications provide their own internal controller, which 
conforms to the controller-to-host specifications. 


DSA disks differ from MASSBUS and UNIBUS disks in the following 
ways: 


¢ DSA disks contain no bad blocks. The hardware and the disk class 
driver (DUDRIVER) function to ensure a logically contiguous range 
of good blocks. If any block in the user area of the disk develops a 
defective area, all further access to that block is revectored to a spare 
good block. Consequently, it is never necessary to run the Bad Block 
Locator Utility (BAD) on DSA disks. There is no manufacturer’s bad 
block list and the file BADBLK.SYS is empty. (The Verify Utility, 
which is invoked by the ANALYZE /DISK_STRUCTURE /READ_ 
CHECK command, can be used to check the integrity of newly received 
disks.) See Section 3.2.10.1 for additional information about bad block 
replacement for DSA disks. 


¢ Insert a WAIT statement in your SYSTARTUP_V5.COM file prior to. 
the first MOUNT statement for a DSA disk. The wait period should 
be about two to four seconds for the UDA50 and about 30 seconds for 
the HSC50. The wait time is controller-dependent and can be as much 
as several minutes if the controller is offline or otherwise inoperative. 
If this wait is omitted, the MOUNT request may fail with a “no such 
device” status. 


¢ The DUDRIVER and the DSA device controllers allow multiple, 
concurrently outstanding QIO requests. The order in which these 
requests complete might not be in the order in which they were issued. 
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e All DSA disks can be dual-ported, but only one HSC/UDA controller 
can control a disk at a time (see Section 3.2.3). 


e In many cases, you can attach a DSA disk to its controller on a 
running VMS operating system and then use it without manual 
intervention. 


e DSA disks and the DUDRIVER do not accept physical QIO data 
transfers or seek operations. 


3.2.10.1 Bad Block Replacement and Forced Errors for DSA Disks 
Disks that are built according to the DSA specifications appear to be error 
free. Some number of logical blocks are always capable of recording data. 
When a disk is formatted, every user-addressable logical block is mapped 
to a functioning portion of the actual disk surface, which is known as 
a physical block. The physical block has the true data storage capacity 
represented by the logical block. 


Additional physical blocks are set aside to replace blocks that fail 
during normal disk operations. These extra physical blocks are called 
replacement blocks. Whenever a physical block to which a logical 
block is mapped begins to fail, the associated logical block is remapped 
(revectored) to one of the replacement blocks. The process that revectors 
logical blocks is called a bad block replacement operation. Bad block 
replacement operations use data stored in a special area of the disk called 
the Replacement and Caching Table (RCT). 


When a drive-dependent error threshold is reached, the need for a bad 
block replacement operation is declared. Depending on the controller 
involved, the bad block replacement operation is performed either by 

the controller itself (as is the case with HSCs) or by the host (as is the 
case with UDAs). In either case, the same steps are performed. After 
inspecting and altering the RCT, the failing block is read and its contents 
are stored in a reserved section of the RCT. 


The design goal of DSA disks is that this read operation proceeds without 
error and that the RCT copy of the data is correct (as it was originally 
written). The failing block is then tested with one or more data patterns. 
If no errors are encountered in this test, the original data is copied back 
to the original block and no further action is taken. If the data-pattern 
test fails, the logical block is revectored to a replacement block. After 

the block is revectored, the original data is copied back to the revectored 
logical block. In all these cases, the original data is preserved and the bad 
block replacement operation occurs without the user being aware that it 
happened. 


However, if the original data cannot be read from the failing block, a 
best attempt copy of the data is stored in the RCT and the bad block 
replacement operation proceeds. When the time comes to write-back the 
original data, the best attempt data (stored in the RCT) is written back 
with the forced error flag set. The forced error flag is a signal that the 
data read is questionable. Reading a block that contains a forced error 
flag causes the status SS$_FORCEDERROR to be returned. This status is 
displayed by the following message: 


SSYSTEM-F-FORCEDERROR, forced error flagged in last sector read 
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Writing into a block always clears the forced error flag. 


Note that most VMS utilities and DCL commands treat the forced error 
flag as a fatal error and terminate operation when they encounter it. 
However, the Backup Utility (BACKUP) continues to operate in the 
presence of most errors, including the forced error. BACKUP continues 
to process the file, and the forced error flag is lost. Thus, data that was 
formerly marked as questionable may become “correct” data. 


System managers (and other users of BACKUP) should assume that forced 
errors reported by BACKUP signal possible degradation of the data. 


To determine what, if any, blocks on a given disk volume have the forced 
error flag set, use the ANALYZE /DISK_STRUCTURE /READ_CHECK 
command, which invokes the Verify Utility. The Verify Utility reads every 
logical block allocated to every file on the disk and then reports (but 
ignores) any forced error blocks encountered. 


3.2.11 VAXstation 2000 and MicroVAX 2000 Disk Driver 


The VAXstation 2000 and MicroVAX 2000 disk driver supports some DSA 
disk operation. In particular, the driver supports block revectoring and 
bad block replacement. This provides the system with a logically perfect 
disk medium. 


Like other DSA disks, if a serious error occurs during a replacement 
operation, the disk is write-locked to prevent further changes. This is done 
to preserve data integrity and minimize damage that could be caused by 
failing hardware. Unlike other DSA disks, there is no visible indication 
on the drive itself that the disk is write-locked. However, the following 
indicators help you determine that the disk has become write-protected: 


¢ ERRFMT messages show that the disk is write-locked. 
¢ The disk enters mount verification and hangs. 


¢ DCL command SHOW DEVICE output shows that the disk is write- 
locked. 


e Error messages from programs and utilities attempting to write to the 
disk. 

If the disk becomes write-locked, you should use the following procedure: 

1 Shut down the system. 

2 Use standalone BACKUP to create a full backup of the disk. 

3 Format the disk with the disk formatter. 

4 


Restore the disk from the backup using standalone BACKUP. Note 
that any files with sectors flagged with a forced error may be corrupted 
and may need to be restored from a previous backup. 


If errors occurring during replacement operations persist, call Digital 
Customer Services. 
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3.2.12 SCSI Disk Class Driver 


The VAXstation 3100, 3520, and 3540 contain a SCSI bus that provides 
access to as many as seven SCSI disks. The SCSI disk class driver controls 
SCSI disks on all of the above systems. Although, SCSI disks do not 
conform to DSA, they do support the following error recovery features: 


¢ Static and dynamic bad block replacement (BBR) 
¢ Error correcting code (ECC) 
e Reexecution of read or write operations within the SCSI drive 


¢ Reexecution of read or write operations by the SCSI disk class driver 


All SCSI disks supplied by Digital implement the REASSIGN BLOCKS 
command which relocates data for a specific logical block to a different 
physical location on the disk. The SCSI disk class driver reassigns the 
block in the following instances: (1) when the retry threshold is exceeded 
during an attempt to read or write a block of data on the disk or (2) when 
an irrecoverable error occurs during a write operation. 


Unlike DSA, there is.no forced error flag in SCSI. Blocks that produce 
irrecoverable errors during read operations are not reassigned in order to 
prevent undetected loss of user data. Instead, the SCSI disk class driver 
returns the SS$_PARITY status whenever a read operation results in an 
irrecoverable error. 


3.3 Disk Driver Device Information 
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You can obtain information on all disk device characteristics by using the 
Get Device/Volume Information (SGETDVI) system service (see the VMS 
System Services Reference Manual). 


$GETDVI returns disk characteristics when you specify the item codes 
DVI$_DEVCHAR and DVI$_DEVCHAR2. Table 3—2 lists the possible 
characteristics for disk devices. 


Table 3-2 Disk Device Characteristics 
Characteristic’ Meaning 


Dynamic Bits (Conditionally Set) 


DEV$M_AVL Device is online and available. 
DEV$M_CDP?% Dual-path device with two UCBs. 
DEV$M_CLU? Device is available clusterwide. 
DEV$M_2P? | Device is dual-pathed. 
DEV$M_FOR Device is foreign. 


'Defined by the $DEVDEF macro. 
2These bits are located in DVI$_DEVCHAR2. 
3MASSBUS only. 
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Table 3~—2 (Cont.) Disk Device Characteristics 


Characteristic’ Meaning 


Dynamic Bits (Conditionally Set) 


DEV$M_MNT Volume is mounted. 

DEV$M_RCK Perform data check all reads. 

DEV$M_WCK Perform data check all writes. 

DEV$M_MSCP? Device is accessed using the mass storage control 
protocol. 

DEV$M_RCT Disk contains Replacement and Caching Table. 

DEV$M_SRV? For a VAXcluster, device is served by the MSCP 
server. 


Static Bits (Always Set) 


DEV$M_FOD Device is file-oriented. 

DEV$M_IDV Device is capable of input. 
DEV$M_ODV Device is capable of output. 
DEV$M_RND Device is capable of random access. 
DEV$M_SHR Device is shareable. 


'Defined by the $DEVDEF macro. 
2These bits are located in DVI$_DEVCHAR2. 


DVI$_DEVBUFSIZ returns the buffer size. The buffer size is the default 
to be used for disk transfers (this default is normally 512 bytes). DVI$_ 
DEVTYPE and DVI$_DEVCLASS return the device type and class names, 
which are defined by the $DCDEF macro. The disk model determines 
the device type. For example, the device type for the RA81 is DT$_RA81. 
(Foreign device types take the form DT$_FD1 through DT$_FD8.) The 
device class for disks is DC$_DISK. 


DVI$_CYLINDERS returns the number of cylinders per volume (that is, 
per disk), DVI$_TRACKS returns the number of tracks per cylinder, and 
DVI$_SECTORS returns the number of sectors per track. Values are 
returned as four-byte decimal numbers. 


DVI$_MAXBLOCK returns the maximum number of blocks (1 block = 512 
bytes) that can be contained on the volume (that is, on the disk). Values 
are returned as four-byte decimal numbers. This information can be used, 
for example, to determine the density of an RX02 diskette (single 

density = 494 blocks, double density = 988 blocks). 
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Note: 


VMS disk drivers can perform logical, virtual, and physical I/O functions. 
Foreign-mounted devices do not require privilege to perform logical and 
virtual I/O requests. 


Logical and physical I/O functions allow access to volume storage and 
require only that the issuing process have access to the volume. However, 
DSA disks and the disk class driver (DUDRIVER) do not accept physical 
QIO data transfers or seek operations. 


The results of logical and physical I/O operations are 
unpredictable if an ancillary control process (ACP) or extended 
QIO processing (XQP) is present. 


Virtual I/O functions require an ACP for Files—11 On-Disk Structure 
Level 1 files or an XQP for Files—11 On-Disk Structure Level 2 files. 
Virtual I/O functions must be executed in a prescribed order. First, you 
create and access a file, then you write information to that file, and lastly 
you deaccess the file. Subsequently, when you access the file, you read 
the information, and then deaccess the file. Delete the file when the 
information is no longer useful. 


Non-DSA disk devices can read or write up to 65,535 bytes in a single 
request. DSA devices connected to an HSC50 can transfer up to 4 billion 
bytes in a single request. In all cases, the maximum size of the transfer 
is limited by the number of pages that can be faulted into the process’s 
working set, and then locked into physical memory. (The disk driver is 
responsible for any memory management functions of this type.) The 
size of the transfer does not affect the applicable quotas (direct I/O count, 
buffered I/O count, and AST count limit). These quotas refer to the 
number of outstanding I/O operations of each type, not the size of the I/O 
operation being performed. 


The volume to which a logical or virtual function is directed must be 
mounted for the function actually to be executed. If it is not mounted, 
either a “device not mounted” or “invalid volume” status is returned in the 
I/O status block. 


Table 3-3 lists the logical, virtual, and physical disk I/O functions and 
their function codes. Chapter 1 describes the QIO level interface to the 
disk device ACP. 


Table 3-3 Disk I/O Functions 


Function Code 


lO$_ACCESS 


lO$_ACPCONTROL 


1O$_AVAILABLE 


lO$_CREATE 


1O$_DEACCESS 


lO$_DELETE 


1O$_FORMAT 
1O$_MODIFY 


lO$_PACKACK 


10$_READLBLK 


10$_READPBLK 


lO$_READVBLK 
1O$_ SEARCH 


lO$_SEEK 


lO$_SENSECHAR 


1O$_SENSEMODE 


Arguments 


P1, [P2],[P3],[P4],[P5] 


P1,[P2],[P3],[P4],[P5] 


P1,[P2],[P3],[P4],[P5] 


P1,[P2],[P3],[P4],[P5] 


P1,(P2],[P3],[P4],{P5} 


P1 
P1,[P2], [P3],[P4],[P5] 


P1,P2,P3 


P1,P2,P3 


P1,P2,P3 
P1 


Pt 


1V = virtual; L = logical; P = physical 


2Not for RXO1 and RX02 


3Not for TU58, RX01, RX02, RBO2, and RLO2 
5Not for DSA and SCSI disks 


Type’ 
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Function 
Modifiers 


IO$M_CREATE 
lO$M_ACCESS 


l\O$M_DMOUNT 


IO$M_CREATE 
lO$M_ACCESS 
lO$M_DELETE 


IO$M_DELETE 


lO$M_DATACHECK® 
lO$M_INHRETRY 


lO$M_DATACHECK? 
IO$M_INHRETRY 
lO$M_INHSEEK® 


lO$M_DATACHECK? 
lIO$M_INHRETRY 
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Function 


Search a directory for a 
specified file and access the 
file if found. 


Perform miscellaneous 
control functions. 


Clear volume valid; make 
DSA units available. 


Create a directory entry ora 
file. 


Deaccess a file and, 
if specified, write final 
attributes in the file header. 


Remove a directory entry or 
file header, or both. 


Set density (RX02 only). 


Modify the file attributes or 
allocation, or both. 


Update UCB fields if RX02; 
initialize volume valid on 
other devices. Bring DSA 
units online. 


Read logical block. 


Read physical block.® 


Read virtual block. 


Search for specified block or 
sector (only for TU58). 


Seek to specified cylinder.® 


Sense the device-dependent 
characteristics and return 
them in the I/O status block. 


Sense the device-dependent 
characteristics and return 
them in the I/O status block. 


(continued on next page) 
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Table 3-3 (Cont.) 


Function Code 
1O$_SETPRFPTH 


1O$_UNLOAD 


lO$_WRITECHECK 


lO$_WRITELBLK 


1O$_WRITEPBLK 


lO$_WRITEVBLK 


Disk I/O Functions 


Arguments 
P41 


P1,P2,P3 


P1,P2,P3 


P1,P2,P3 


P1,P2,P3 


'V = virtual; L = logical; P = physical 


2Not for RXO1 and RX02 


3Not for TU58, RX01, RX02, RBO2, and RLO2 


4RX02 only 


5Not for DSA and SCSI disks 
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Type’ 


Function 
Modifiers 


lO$M_FORCEPTH 


1O$M_DATACHECK? 
1O$M_ERASE 
IO$M_INHRETRY 


1O$M_DATACHECK? 
lO$M_ERASE 
IO$M_INHRETRY 
|O$M_INHSEEK® 
|O$M_DELDATA‘ 


lO$M_DATACHECK? 
lIO$M_ERASE 
lO$M_INHRETRY 


Function 


Specifies a preferred path 
for DSA disks. 


Clear volume valid; make 
DSA units available and spin 
down the volume. 


Verify data written to disk by 
a previous write QIO.? 


Write logical block. 


Write physical block.® 


Write virtual block. 


The function-dependent arguments for IO$_CREATE, I0$_ACCESS, 
I10$_DEACCESS, I10$_MODIFY, and IO$_DELETE are as follows: 


e Pi—The address of the file information block (FIB) descriptor. 


¢ P2—The address of the file name string descriptor (optional). If 
specified, the name is entered in the directory specified by the FIB. 


¢ P3—The address of the word that is to receive the length of the 
resulting file name string (optional). 


e P4—The address of a descriptor for a buffer that is to receive the 
resulting file name string (optional). 


e P5—The address of a list of attribute descriptors (optional). If 
specified, the indicated attributes are read (IO$_ACCESS) or written 
(I10$_CREATE, I0$_DEACCESS, and IO$_MODIFY). 


See Chapter 1 for more information on these functions. 


The function-dependent arguments for IO$_READVBLK, I0$_ 
READLBLK, IO$_WRITEVBLK, and IO$_WRITELBLK are as follows: 


¢ Pi—tThe starting virtual address of the buffer that is to receive the 
data from a read operation; or, in the case of a write operation, the 
virtual address of the buffer that is to be written on the disk. 
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P2—The number of bytes that are to be read from the disk, or written 
from memory to the disk. An even number must be specified if the 
controller is an RK611, RL11, RX211, or UDA50O. 


P38—The starting virtual/logical disk address of the data to be 
transferred in a read operation; or, in a write operation, the disk 
address of the area that is to receive the data. 


In a virtual read or write operation, the address is expressed as a 
block number within the file, that is, block 1 of the file is virtual block 
1. (Virtual block numbers are converted to logical block numbers using 
mapping windows that are set up by the file system ACP process.) 


In a logical read or write operation, the address is expressed as a block 
number relative to the start of the disk. For example, the first sector 
on the disk contains block 0 (or at least the beginning of block 0). 


The function-dependent arguments for IO$_WRITEVBLK, 
I0$_WRITELBLK, and IO$_WRITEPBLK functions that include the 
IO$M_ERASE function modifier are as follows: 


Note: 


P1—the starting virtual address of the buffer that contains a four- 
byte, user-specified erase pattern. If the Pl address is 0, a longword of 
O will be used for the erase pattern. If the P1 address is nonzero, the 
contents of the four bytes starting at that address will be used as the 
erase pattern. Digital recommends that the user specify a Pl address 
of 0 to lower system overhead. 


DSA disk controllers provide controlled, assisted erasing for 
the IO$M_ERASE modifier (with virtual and logical write 
functions) only when the erase pattern is all 0s. If a nonzero 
erase pattern is used, there is a significant performance 
degradation with these disks. DSA disks do not accept physical 
QIO transfers. 


P2—The number of bytes of erase pattern to write to the disk. The 
number specified is rounded up to the next highest block boundary 
(512 bytes). 


P3—The starting virtual, logical, or physical disk address of the data 
to be erased. 


The function-dependent arguments for IO$_WRITECHECK, 
I0$_READPBLK, and IO$_WRITEPBLK are as follows: 


P1—tThe starting virtual address of the buffer that is to receive the 
data in a read operation; or, in a write operation, the starting virtual 
address of the buffer that is to be written on the disk. Passed by 
reference. 


P2—The number of bytes that are to be read from the disk, or written 
from memory to the disk. Passed by value. An even number must be 
specified if the controller is an RK611, RL11, or UDA5O. 
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e P3—The starting physical disk address of the data to be read in a 
read operation; or, in a write operation, the starting physical address 
of the disk area that is to receive the data. Passed by value. The 
address is expressed as sector, track, and cylinder in the format shown 
in Figure 3-3. (On the RX01 and RX02, the high word specifies the 
track number rather than the cylinder number.) Check the UCB of a 
currently mounted device to determine the maximum physical address 
value for that type of device. 


Note: On the RB80 and RM80, do not address cylinders 560 and 561. 


These two cylinders are used for diagnostic testing only. 


The function-dependent argument for IO$_SEARCH is as follows: 


¢ P1i—tThe physical disk address where the tape is positioned. The 
address is expressed as sector, track, and cylinder in the format shown 
in Figure 3-3. 


Figure 3-3 Starting Physical Address 


31 16 15 8 7 0 


P3: Cylinder Track | Sector 


(Except RX01 and RX02) 


31 16 15 0 


pos [as 


(RX01 and RX02 Only) 


ZK-0652-GE 


The function-dependent argument for I0$_SEEK is as follows: 


e P1i—tThe physical cylinder number where the disk heads are 
positioned. The address is expressed in the format shown in 
Figure 3—4. 


Figure 3-4 Physical Cylinder Number Format 


31 16 15 0 
Not Used Cylinder 
ZK-0653-GE 


3.4.1 


Read 
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The function dependent argument for IO$_FORMAT is as follows: 


¢ P1—The density at which an RX02 diskette is reformatted (see 
Section 3.4.4). 


The read function reads data into a specified buffer from disk starting at a 
specified disk address. 


The VMS operating system provides the following read function codes: 
¢ I0$ READVBLK—Read virtual block 

¢ I0$ READLBLK—Read logical block 

¢ IO$ READPBLK—Read physical block 


If a read virtual block function is directed to a volume that is mounted 
foreign, that function is converted to read logical block. If a read virtual 
block function is directed to a volume that is mounted structured, the 
volume is handled in the same way as for a file-structured device. 


Three function-dependent arguments are used with these codes: Pl, P2, 
and P38. These arguments are described in Section 3.4. 


The data check function modifier (IO$M_DATACHECK) can be used with 
all read functions. If this modifier is specified, a data check operation is 
performed after the read operation completes. A data check operation is 
also performed if the volume that has been read, or the volume on which 
the file resides (virtual read), has the characteristic “data check all reads.” 
Furthermore, a data check is performed after a virtual read if the file has 
the attribute “data check on read.” The RX01 and RX02 drivers do not 
support the data check function. 


If IO$M_DATACHECK is specified with a read function code to a TU58, 
or if the volume read has the characteristic “data check all reads,” a 
read check operation is performed. This alters certain TU58 hardware 
parameters when the tape is read. (The read threshold in the data 
recovery circuit is increased; if the tape has any weak spots, errors are 
detected.) 


The data check function modifier to a disk or tape can return five error 
codes in the I/O status block: 

SS$_CTRLERR SS$_DRVERR SS$_MEDOFL 

SS$_NONEXDRV SS$ NORMAL 


If no errors are detected, the disk or tape data is considered reliable. 


The inhibit retry function modifier IO$M_INHRETRY) can be used 
with all read functions. If this modifier is specified, all error recovery 
attempts are inhibited. IO$M_INHRETRY takes precedence over IO$M_ 
DATACHECK. If both are specified and an error occurs, there is no 
attempt at error recovery and no data check operation is performed. If 
an error does not occur, the data check operation is performed. 
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The write function writes data from a specified buffer to disk starting at a 
specified disk address. 


The VMS operating system provides the following write function codes: 
e JO$ WRITEVBLK—Write virtual block 

¢ I0$ WRITELBLK—Write logical block 

e 10$ WRITEPBLK—Write physical block 


If a write virtual block function is directed to a volume that is mounted 
foreign, the function is converted to write logical block. If a write virtual 
block function is directed to a volume that is mounted structured, the 
volume is handled in the same way as for a file-structured device. 


Three function-dependent arguments are used with these codes: P1, P2, 
and P38. These arguments are described in Section 3.4. 


The data check function modifier (IO$M_DATACHECK) can be used with 
all write operations. If this modifier is specified, a data check operation 
is performed after the write operation completes. A data check operation 
is also performed if the volume written, or the volume on which the file 
resides (virtual write), has the characteristic “data check all writes.” 
Furthermore, a data check is performed after a virtual write if the file has 
the attribute “data check on write.” The RX01 and RX02 drivers do not 
support the data check function. 


If IO$M_DATACHECK is specified with a write function code to a TU58, 
or if the volume written has the characteristic “data check all writes,” a 


write check operation is performed. The write check verifies data written 


on the tape. First, the specified data is written on the tape. Then the tape 
is reversed and the TU58 controller reads the data internally to perform 
a checksum verification. If the checksum verification is unsuccessful after 
eight attempts, the write check operation is aborted and an error status is 
returned. 


The inhibit retry function modifier (IO$M_INHRETRY) can be used 

with all write functions. If that modifier is specified, all error recovery 
attempts are inhibited. IO$M_INHRETRY takes precedence over 
IO$M_DATACHECK. If both IO$M_INHRETRY and IO$¢M_DATACHECK 
are specified and an error occurs, there is no attempt at error recovery, 
and no data check operation is performed. If an error does not occur, the 
data check operation is performed. IO$M_INHRETRY has no affect on 
DSA disks. 


The write deleted data function modifier (IO$M_DELDATA) can be used 
with the write physical block (IO$_WRITEPBLK) function to the RX02. 
If this modifier is specified, a deleted data address mark instead of the 
standard data address mark is written preceding the data. Otherwise, 
the operation of the IO$_WRITEPBLK function is the same; write data is 
transferred to the disk. When a successful read operation is performed on 
this data, the status code SS$_RDDELDATA is returned in the I/O status 
block rather than the usual SS$_ NORMAL status code. 


3.4.3 


3.4.4 


3.4.5 


Sense Mode 


Set Density 


Search 
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The IO$M_ERASE function modifier can be used with all write function 
codes to erase a user-selected part of a disk. This modifier propagates an 
erase pattern through the specified range. Section 3.4 describes the write 
function arguments to be used with IO$M_ERASE. 


Sense mode operations obtain current disk device-dependent 
characteristics that are returned to the caller in the second longword of 
the I/O status block (see Figure 3-6). The VMS operating system provides 
the following function codes: 


¢ JO$ SENSEMODE—Sense characteristics 
e JO$ SENSECHAR—Sense characteristics 


I0$_SENSEMODE is a logical function. IO$_SENSECHAR is a physical 
I/O function and requires the access privilege necessary to perform 
physical I/O. No device- or function-dependent arguments are used with 
either function. 


The set density function assigns a new density to an entire RX02 floppy 
diskette. The diskette is also reformatted: new data address marks 

are written (single or double density) and all data fields are zeroed. 

Set density is a physical I/O function and requires the access privilege 
necessary to perform physical I/O. The following function code is provided: 


¢ 10$_FORMAT 


| I0$_FORMAT takes the following function-dependent argument: 


e P1—tThe density at which the diskette is reformatted: 


0 = single density (default) 
1 = single density 
2 = double density 


The set density operation should not be interrupted before it is completed 
(about 15 seconds). If the operation is interrupted, the resulting diskette 

might contain illegal data address marks in both densities. The diskette 

must then be completely reformatted and the function reissued. 


The search function positions a TU58 magnetic tape to the block specified. 
Search is a physical J/O function and requires the access privilege 
necessary to perform physical I/O. The VMS operating system provides 

a single function code: 


¢ I0$_SEARCH 
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This function code takes the following function-dependent argument: 


¢ Pi—Specifies the block where the read/write head will be positioned. 
The low byte contains the sector number in the range 0 to 127; the 
high byte contains the track number in the range 0 to 3. 


I0$_SEARCH can save time between read and write operations. For 
example, nearly 30 seconds are required to completely rewind a tape. If 
the last read or write operation is near the end of the tape and the next 
operation is near the beginning of the tape, the search operation can begin 
after the last operation completes, and the tape will rewind while the 
process is otherwise occupied. (The search QIO is not completed until the 
search is completed. Consequently, if a $QIOW system service request is 
issued, the process will be held up until the search is completed.) 


Pack Acknowledge 


Unload 
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The pack acknowledge function sets the volume valid bit for all disk 
devices. Pack acknowledge is a physical I/O function and requires the 
access privilege to perform physical I/O. If directed to an RX02 drive, 
pack acknowledge also determines the diskette density and updates 

the device-dependent information returned by $GETDVI item codes 
DVI$_CYLINDERS, DVI$_TRACKS, DVI$_SECTORS, DVI$_DEVTYPE, 
DVI$_CLASS, and DVI$_MAXBLOCK. If directed to a DSA disk, pack 
acknowledge also sends the online packet to the controller. The following 
function code is provided: 


¢ JO$_PACKACK 


This function code takes no function-dependent arguments. 


I0$_PACKACK must be the first function issued when a volume (pack, 
cartridge, or diskette) is placed in a disk drive. IO$_PACKACK is issued 
automatically when the DCL commands INITIALIZE or MOUNT are 
issued. 


For DSA disks, the IO$_PACKACK function locks the drive’s port selector 
on the port that initiated the pack acknowledge function. 


In addition, the IO$_PACKACK function updates device-dependent 
information about DSA disks returned by $GETDVI. 


The unload function clears the volume valid bit for all disk drives, makes 
DSA disks available, and issues an unload command to the drive (spins 
down the volume). The unload function reverses the function performed 
by pack acknowledge (see Section 3.4.6). The following function code is 
provided: 


¢ IO$_UNLOAD 


This function takes no function-dependent arguments. 


3.4.8 Available 


3.4.9 Seek 


3.4.10 Write Check 
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The available function clears the volume valid bit for all disk drives; 
that is, it reverses the function performed by pack acknowledge (see 
Section 3.4.6). No unload function is issued to the drive. Therefore, those 
drives capable of spinning down do not spin down. The following function 
code is provided: 


¢ JIO$_AVAILABLE 


This function takes no function-dependent arguments. 


The seek function directs the read/write heads to move to the cylinder 
specified in the P1 argument (see Sections 3.2.7 and 3.4, and Figure 3-4). 


The write check function verifies that data was written to disk 

correctly. The data to be checked is addressed using physical disk 
addressing (sector, track, and cylinder) (see Figure 3-3). If the request 
is directed to a DSA disk, you must specify a logical block number, even 
though I0$_WRITECHECK is a physical I/O function. The following 
function code is provided: 


e I0$_WRITECHECK 


A write QIO must be used to write data to disk before you enter this 
command. I0$_WRITECHECK then reads the same block of data and 
compares it with the data in the specified buffer. Three function-dependent 
arguments are used with this code: Pl, P2, and P38. These arguments are 
described in Section 3.4. 


10$_WRITECHECK is similar to the IO$M_DATACHECK function 
modifier for write QIOs, except that IO$_WRITECHECK does not write 
the data to disk; it is specified after data is written by a separate write 
QIO. Nonprivileged processes can use the IO$M_DATACHECK modifier 
with I0$_WRITEVBLK (which does not require access privilege) to 
determine whether data is written correctly. The RX01 and RX02 drivers 
do not support the write check function. 


The write check function and the data check function modifier to a TU58 
can return six error codes in the I/O status block: SS$_NORMAL, 
SS$_CTRLERR, SS$_DRVERR, SS$_MEDOFL, SS$_NONEXDRYV, and 
SS$_WRTLCK. 
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The set preferred path function specifies a preferred path for DSA disks. 
This includes RA-series disks and disks accessed through the MSCP 
server. If a preferred path is specified for a disk, the MSCP disk class 
drivers (DUDRIVER and DSDRIVER) use the path as their first attempt 
to locate the disk and bring it on line as a result of a DCL command 
MOUNT or failover of an already mounted disk. In addition, you can 
initiate failover of a mounted disk in order to force the disk to the 
preferred path, or to use load-balancing information for disks accessed 
through MSCP servers. 


The function code is: 
I0$_SETPRFPTH 


The following is the function modifier: 


¢ JO$M_FORCEPATH—causes the disk class driver to select the server 
path with the highest load available rating. 


The Pl parameter contains the address of a counted ASCII string 
(.ASCIC). This string is the node name of the HSC or VMS system that 
is the preferred path. The node name must match an existing node that 
is known to the local node and if the node is a VMS system, it must be 
running the MSCP server. This function does not move the disk to the 
preferred path. 


The PHYS_IO privilege is required for IO$_SETPRFPTH and 
IO$M_FORCEPATH. 


The following example shows the use of IO$_SETPRFPTH: 


Sassigndef 

Sqiodef 

Siodef 

Sexitdef 
dev: .ascid /$254SDUA48:/ 
chnl: -word 0 
node: -ascic /HSC001/ 


-entry start,0 


Sassign_s devnam=dev, - 
: chan=chnl 
blbec r0,done 


$qiow_s chan=chn1l, - 
func=#10$_SETPRFPTH, - 
pl=node 


done: 
Sexit_s r0 


-end start 


This updates the local node I/O database to indicate that node HSCO001 is 
the preferred path for DUA48. 
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3.4.11.1 Forcing a Path Change 
You can move a disk that is already mounted to its preferred path by 
specifying the IO$M_FORCEPATH modifier. If a preferred path has not 
been specified for a disk that is accessed through the MSCP server, the 
IO$M_FORCEPATH function causes the disk class driver to use load- 
balancing information to select the server path with the highest load 
available rating. 


IO$M_FORCEPATH does not accept any arguments. If you intend to 
move a disk to its preferred path, you must specify the preferred path in a 


separate $QIO function. 
The following example shows use of the IO$M_FORCEPATH function 
modifier: 
Sassigndef 
Sqiodef 
Siodef 
Sexitdef 
dev: -ascid /$254SDUA197:/ 
chnil: -word 0 


-entry start,0 


Sassign_s devnam=dev, —- 
chan=chnl 
blbc r0,done 
Sqiow_s chan=chnl, - 
func=#<I0$_SETPRFPTH! IO$M_FORCEPATH> 


done: 
Sexit_s x0 


-end start 


Note that forcing a path change places the disk in mount verification. New 
I/O requests are suspended until mount verification is complete. 


3.4.11.2 Using |O$¢ SETPRFPTH with Disks Dual Pathed Between HSCs 
You can use the IO$_SETPRFPTH and IO$M_FORCEPATH functions 
to load balance disks that are dual pathed between HSCs. The IO$M_ 
FORCEPATH function initiates failover of the disk on all nodes that 
have it mounted and that have a direct path to the HSCs. Since the 
node that issues the IO$M_FORCEPATH might not be the first one to 
attempt failover of the disk, it is essential that all nodes that have direct 
connections to the HSCs specify the same preferred path for the disk. 
Only one node should issue the IO$M_FORCEPATH request. 


3.4.11.3 Using 1O0$_SETPRFPTH with Disks Dual Pathed Between VMS Systems 
You can use IO$M_FORCEPATH to load balance RA-series disks that 
are dual pathed between VMS systems running the MSCP server. Both 
serving nodes should specify the same preferred path. In order to move 
the disk between VMS systems, the system that currently has the disk 
on line through its local controller should issue the IO$M_FORCEPATH 
request. The disk must be mounted on both serving nodes. 
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3.4.11.4 Using 1O$_SETPRFPTH with Disks Accessed Through MSCP Servers 


You can specify a preferred path for disks that are accessed through MSCP 
servers. However, this specification overrides any load-balancing decisions. 


Note that if a disk can be accessed through both HSC and MSCP servers, 
you need not specify the HSC as a preferred path. HSC paths are always 
preferred to server paths. 


Using IO$M_FORCEPATH without a preferred path causes the disk class 
driver to move the disk to the server with the highest available capacity. 


3.4.11.5 Using l|O$_SETPRFPTH with Phase | Volume Shadowing 


You can specify IO$_SETPRFPTH for shadow set members, but not 
for virtual units. IO$M_FORCEPATH is not supported for shadow set 
members or virtual units. 


3.4.11.6 Using 1O$ SETPRFPTH with Phase II Volume Shadowing 


IO0$_SETPRFPTH and IO$M_FORCEPATH are supported for shadow set 
members but not for virtual units. 





I/O Status Block 
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Figure 3-5 shows the J/O status block (IOSB) for all disk device QIO 
functions except Sense Mode. Figure 3-6 shows the I/O status block 
for the Sense Mode function. Appendix A lists the status messages for 
all functions and devices. (The VMS System Messages and Recovery 
Procedures Reference Manual provides explanations and suggested user 
actions for these messages.) 


Figure 3-5 1IOSB Contents 


31 16 15 P 
Byte Count 
Byte Count 
(High—Order Word) 





ZK-0656-—GE 


The byte count is a 32-bit integer that gives the actual number of bytes 
transferred to or from the process buffer. 
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Figure 3-6 IOSB Contents for the Sense Mode Function 


31 16 15 8 7 0 
Status 





Cylinders Tracks Sectors 


ZK-0657-GE 


The second longword of the I/O status block for the Sense Mode function 
returns information about the cylinder, track, and sector configurations for 
the particular device. 





3.6 Disk Driver Programming Example 


This sample program (Example 3-1) provides an example of optimizing 
access time to a disk file. The program creates a file using VMS RMS, 
stores information concerning the file, and closes the file. The program 
then accesses the file and reads and writes to the file using the Queue I/O 
($QIO) system service. 
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Example 3-1 Disk Program Example 





: KEK KKK KKK KEK KK KEK KKK KKK KKK KKK KKK KEKE KKK KE KKK KKK KKK RK KE KKKEKKEKKKKKKKKKKEKKKK 
; 

-TITLE Disk Driver Programming Example 

-IDENT /01/ 


; Define necessary symbols. 


SFIBDEF ;Define file information block Offsets 
SIODEF ;Define. I/O function codes 
SRMSDEF ;Define RMS-32 Return Status Values 


7 Local storage 
; Define number of records to be processed. 


NUM_RECS=100 7One hundred records 


. 
, 


; Allocate storage for necessary data structures. 


; Allocate File Access Block. 
i A file access block is required by RMS-32 to open and close a 
7 file. 


e 
7 


FAB BLOCK: : 

SFAB ALQ = 100,- ;Initial file size is to be 
= 7100 blocks 
FAC = PUT,- ;File Access Type is output 
FNA = FILE NAME, - ;File name string address 
FNS = FILE SIZE,- ;File name string size 
FOP = CTG,- ;File is to be contiguous 
MRS = 512,- ;Maximum record size is 512 
- ;bytes 
NAM = NAM BLOCK, - ;File name block address 
ORG = SEQ,- ;File organization is to be 
a ; sequential 
REM = FIX ;Record format is fixed length 


} Allocate file information block. 


; A file information block is required as an argument in the 
; Queue I/O system service call that accesses a file. 
FIB_ BLOCK: ; 

. BLKB FIBS$K_LENGTH ; 


; 
; Allocate file information block descriptor. 


° 
, 


FIB_DESCR: ; 
. LONG FIBSK_LENGTH ;Length of the file 
;information block 
-LONG FIB BLOCK #Address of the file 


j;information block 





(continued on next page) 


3-38 


Disk Drivers 
3.6 Disk Driver Programming Example 


Example 3-1 (Cont.) Disk Program Example 





; Allocate File Name Block 


e 
r 


; A file name block is required by RMS-32 to return information 
; concerning a file (for example, the resultant file name string 
; after logical name translation and defaults have been applied). 
NAM_BLOCK: ; 

SNAM ; 


; Allocate Record Access Block 


° 
f 


; A record access block is required by RMS-32 for record 
; operations on a file. 
RAB BLOCK: 
SRAB FAB = FAB BLOCK, - ;File access block address 
RAC = SEQ,- ;Record access is to be 
- ; sequential 
RBF = RECORD_BUFFER, - ;Record buffer address 
RSZ = 512 ;Record buffer size 


3; Allocate direct address buffer 
BLOCK_BUFFER: 


. BLKB 1024 ;Direct access buffer is 1024 
;bytes 


; Allocate space to store channel number returned by the SASSIGN 
; Channel system service. 
DEVICE CHANNEL: ; 

. BLKW 1 ; 


; Allocate device name string and descriptor. 


. 
7 


DEVICE DESCR: ; 
. LONG 20$-10$ ;Length of device name string 
. LONG 10$ s;Address of device name string 
10s: -ASCII /SYSSDISK/ ;Device on which created file 
;will reside 
208: ;Reference label to calculate 
;length 


+; Allocate file name string and define string length symbol. 


e 
’ 


FILE_NAME: ; 
-ASCII /SYSSDISK:MYDATAFIL.DAT/ ;File name string 


FILE SIZE=.-FILE NAME ;File name string length 


. 
’ 


; Allocate I/O status quadword storage. 


=e 
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IO STATUS: : 
- BLKQ 1 ; 
; Allocate output record buffer. 
r 
RECORD_BUFFER: ; 
. BLKB 512 ;Record buffer is 512 bytes 


KKKKKKKEKKKKKKKKKKKEKKEKKKKK KEK KEK KKK KKK KK KKK KE KKK KKK KKKKKKKKKKKKRKKKKEKE 


; Start Program 


KKKKKKKKKKKKKKKKKKKKKKKKEKKKKKK KKK KKK KK KKK RK KK KKK KKKKKKKKKKKKKKKKKKEKK 


; The purpose of the program is to create a file called MYDATAFIL.DAT 
7 using RMS-32; store information concerning the file; write 100 

; records, each containing its record number in every byte; 

; close the file; and then access, read, and write the file directly, 
7; using the Queue I/O system service. If any errors are detected, the 
; program returns to its caller with the final error status in 

7 register RO. 


-ENTRY DISK_EXAMPLE, “M<R2,R3,R4,R5,R6> ;Program starting 
yaddress 


; First create the file and open it, using RMS-32. 


PART 1: ;First part of example 
SCREATE FAB = FAB BLOCK ;Create and open file 
BLBC RO, 208 ;If low bit = 0, creation 
;failure 


; Second, connect the record access block to the created file. 


SCONNECT RAB = RAB BLOCK ;Connect the record access 
;block 

BLBC RO, 308 ;If low bit = 0, creation 
;failure 


7 Now write 100 records, each containing its record number. 
MOVZBL #NUM_RECS,R6 ;Set record write loop count 
; Fill each byte of the record to be written with its record number. 


10S: SUBB3 R6, #NUM_RECS+1,R5 ;Calculate record number 
MOVCS5 #0, (R6),R5,#512,RECORD BUFFER ;Fill record buffer 


7 Now use RMS-32 to write the record into the newly created file. 


e 
v 
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SPUT RAB = RAB BLOCK ;Put record in file 
BLBC RO, 30$ ;If low bit = 0, put failure 
SOBGTR R6,10$ ;Any more records to write? 


; The file creation part of the example is almost complete. All that 
; remains to be done is to store the file information returned by 
; RMS-32 and close the file. 


MOVW NAM BLOCK+NAMSW_FID,FIB BLOCK+FIBSW_FID ;Save file 
;identification 

MOVW NAM _BLOCK+NAMSW_FID+2,FIB BLOCK+FIBSW_FID+2 ;Save 
;sequence number 

MOVW NAM BLOCK+NAMSW_FID+4,FIB BLOCK+FIBSW_FID+4 ;Save 
;relative volume 


SCLOSE FAB = FAB BLOCK ;Close file 
BLBS RO,PART 2 ;If low bit set, successful 
;close 
208 RET ;Return with RMS error status 


; 
; Record stream connection or put record failure. 
7 


; Close file and return status. 


308: PUSHL RO ;Save error status 
SCLOSE FAB = FAB BLOCK #Close file 
POPL RO ;Retrieve error status 
RET ;Return with RMS error status 


; The second part of the example illustrates accessing the previously 
; created file directly using the Queue I/O system service, randomly 
; reading and writing various parts of the file, and then deaccessing 
; the file. 


; First, assign a channel to the appropriate device and access the 
; file. 
PART 2: ; 
SASSIGN_S DEVNAM = DEVICE DESCR,- ;Assign a channel to file 
CHAN = DEVICE CHANNEL ; device 


BLBC RO,20$ ;If low bit = 0, assign 
;failure 
MOVL #FIBSM NOWRITE!FIBSM WRITE, - Set for read/write 
FIB BLOCK+FIB$L_ACCTL ;access 


SQIOW_S CHAN = DEVICE CHANNEL,- ;Access file on device channel 


FUNC = #IO0$_ACCESS!IO$M_ACCESS,- ;I/O function is 
oa ;access file 
IOSB = IO_STATUS,- ;Address of I/O status 
- ;Quadword 
Pl = FIB DESCR ;Address of information block 
; descriptor 
BLBC RO,10$ ;If low bit = 0, access 
;failure 
MOVZWL IO _STATUS,RO ;Get final I/O completion 
;status 


(continued on next page) 
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BLBS RO, 30$ ;If low bit set, successful 
;I1/O function 
10S: PUSHL RO ;Save error status 
SDASSGN_S CHAN = DEVICE CHANNEL ;Deassign file device channel 
POPL RO ;Retrieve error status 


208: RET ;Return with I/O error status 


; The file is now ready to be read and written randomly. Since the 

7; records are fixed length and exactly one block long, the record 

* number corresponds to the virtual block number of the record in the 
; file. Thus a particular record can be read or written simply by 

; specifying its record number in the file. 


; The following code reads two records at a time and checks to see 
; that they contain their respective record numbers in every byte. 
; The records are then written back into the file in reverse order. 
; This results in record 1 having the old contents of record 2 and 
; record 2 having the old contents of record 1, and so forth. After 
; the example has been run, it is suggested that the file dump 

7 utility be used to verify the change in data positioning. 


30$ MOVZBL #1,R6 ;Set starting record (block) 
snumber 


; Read next two records into block buffer. 


° 
’ 


40S: $QIO S CHAN = DEVICE CHANNEL,- ;Read next two records from 
= ;file channel 
FUNC = #I0$ READVBLK,~ ;I/0 function is read virtual 
- iblock 
IOSB = IO_STATUS,- sAddress of I/O status 
= ;quadword 
Pl = BLOCK_BUFFER, - ;Address of I/O buffer 
P2 = #1024,- ;Size of I/O buffer 
P3 = R6 ;Starting virtual block of 
;transfer 
BSBB 50$ ;Check I/O completion status 


; 
; Check each record to make sure it contains the correct data. 


. 
7 


SKPC R6, #512, BLOCK_BUFFER ;Skip over equal record 
;numbers in data 


BNEQ 60$ ;I£f not equal, data match 
; failure 
ADDL3 #1,R6,R5 ;Calculate even record number 


SKPC R5,#512,BLOCK_BUFFER+512 ;Skip over equal record 
;numbers in data 

BNEQ 60$ ;If not equal, data match 
;failure 


; Record data matches. 


; Write records in reverse order in file. 
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SQTOW_S CHAN = DEVICE _CHANNEL,- ;Write even-numbered record in 


7 ;odd slot 

FUNC = #IO$ WRITEVBLK,- ;I/O function is write virtual 
= ;block 

IOSB = IO STATUS, - sAddress of I/O status 


_ ;quadword 


Pi = BLOCK_BUFFER+512,- ;Address of even record buffer 

P2 = $512,- ;Length of even record buffer 

P3 = R6 ;Record number of odd record 
BSBB 50$ ;Check I/O completion status 
ADDL3 #1,R6,R5 ;Calculate even record number 


SQIOW_S CHAN = DEVICE _CHANNEL,- ;Write odd numbered record in 
a seven slot 
FUNC = #I0$_WRITEVBLK,- ;1/0 function is write virtual 


= sblock 
IOSB = IO STATUS,- ;Address of I/O status 
= ;quadword 
Pl = BLOCK_BUFFER, — ;Address of odd record buffer 
P2 = #512,- ;Length of odd record buffer 
P3 = R5 ;Record number of even record 
BSBB 50$ 7Check I/O completion status 
ACBB #NUM_RECS~1, #2,R6,40$ 7Any more records to be read? 
BRB 70$ ; 
; Check I/O completion status. 
50S: BLBC RO, 70$ ;If low bit = 0, service 
; failure 
MOVZWL IO _STATUS,RO ;Get final I/O completion 
7status 
BLBC RO, 70$ ;If low bit = 0, I/O function 
RSB ; failure 
; Record number mismatch in data. 
60S; MNEGL #4,R0 7;Set dummy error status value 


° 
, 


; All records have been read, verified, and odd/even pairs inverted 


70$: PUSHL RO ;Save final status 
$QIOW_S CHAN = DEVICE_CHANNEL,- ;Deaccess file 
FUNC = #I0$ DEACCESS 71/0 function is deaccess file 
SDASSGN_S CHAN = DEVICE CHANNEL ;Deassign file device channel 
POPL RO ;Retrieve final status 
RET ; 


END DISK_EXAMPLE 
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4.1 


4.1.1 


Laboratory Peripheral Accelerator Driver 


This chapter describes the VMS laboratory peripheral accelerator 
(LPA11-K) driver and the high-level language procedure library that 
interfaces with it. The procedure library is implemented with callable 
assembly language routines that translate arguments into the format 
required by the LPA11-K driver and that handle buffer chaining 
operations. Routines for loading the microcode and initializing the device 


are also described. 


Refer to the LPA11-K Laboratory Peripheral Accelerator User’s Guide for 
additional information. 





Supported Device 


The LPA11-K is a peripheral device that controls analog-to-digital (A/D) 
and digital-to-analog (D/A) converters, digital I/O registers, and real-time 
clocks. It is connected to the VAX processor through the UNIBUS adapter. 


The LPA11-K is a fast, flexible microprocessor subsystem designed for 
applications requiring high-speed, concurrent data acquisition and data 
reduction. The LPA11-K allows aggregate analog input and output rates of 
up to 150,000 samples per second. The maximum aggregate digital input 
and output rate is 15,000 samples per second. 


Table 4-1 lists the useful minimum and maximum LPA11-K configurations 
supported by the VMS operating system. 


LPA11-K Modes of Operation 


The LPA11-K operates in two modes: dedicated and multirequest. 


In dedicated mode, only one user (one request), can be active at a time, and 
only analog I/O data transfers are supported. Up to two A/D converters 
can be controlled simultaneously. One D/A converter can be controlled at a 
time. Sampling is initiated either by an overflow of the real-time clock or 
by an externally supplied signal. Dedicated mode provides sampling rates 
of up to 150,000 samples per second. 


4.1.2 
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Table 4—1 Minimum and Maximum Configurations per LPA11-K 


Minimum Maximum 

1 DD11-Cx or Dx backplane 2 DD11-Cx or Dx backplanes 

1 KW11-K real-time clock 1 KW11-K real-time clock 

1 of the following: 2 AD11-K A/D converters 
AD11-K A/D converter 2 AM11-K multiplexers for AD11-K converters 
AA11-K A/D converter 1 AA11-K D/A converter 


DR11-K digital 1/O register 5 DR11-K digital I/O registers 


In multirequest mode, sampling from all of the devices listed in Table 4—1 
is supported. The LPA11-K operates like a multicontroller device; up to 
eight requests (from one through eight users) can be active simultaneously. 
The sampling rate for each user is a multiple of the common real-time 
clock rate. Independent rates can be maintained for each user. Both 

the sampling rate and the device type are specified as part of each data 
transfer request. Multirequest mode provides a maximum aggregate 
sampling rate of 15,000 samples per second. 


The LPA11-K returns the following classes of errors: 


1. Errors associated with the issuance of a new LPA11-K command 
(SS$_DEVCMDERR) 


2 Errors associated with an active data transfer request 
(SS$_DEVREQERR) 


3 Fatal hardware errors that affect all LPA11-K activity 
(SS$_CTRLERR) 


The LPA11-K Laboratory Peripheral Accelerator User’s Guide lists these 
three classes of errors and the specific error codes for each class. The 
LPA11-K aborts all active requests if any of the following conditions occur: 


¢ Power failure 
© Device timeout 


e Fatal error 


Power failure is reported to any active users when power is recovered. 


The LADRIVER times out all $QIOs after two seconds if they have not 
completed. The driver does not provide any parameters that allow the 
user to change the length of the timeout. 
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The timeout period applied to all $QIOs can be changed with the following 
PATCH commands executed from a privileged account: 


$ PATCH SYSSSYSTEM: LADRIVER.EXE/OUTPUT=SYSSSYSTEM: LADRIVER. EXE 
PATCH> SET ECO 25 
PATCH> REPLACE/INSTRUCTION LASTIMEOUT_VALUE 


OLD> ’PUSHL I*#00000002’ 
OLD> EXIT 
NEW> ’PUSHL I*#0000003C’ 
NEW> EXIT 


PATCH> UPDATE 
PATCH> EXIT 


Substitute the desired timeout value for the “0000003C” in the example 
above. When you reboot, the system loads the new copy. of the driver 
containing the new timeout value. 


Device timeouts are monitored only when a new command is issued. For 
data transfers, the time between buffer full interrupts is not defined. 
Thus, no timeout errors are reported on a buffer-to-buffer basis. — 


If a required resource is not available to a process, an error message 
is returned immediately. The driver does not place the process in the 
resource wait mode. 





4.2 Supporting Software 


The LPA11-K is supported by a device driver, a high-level language 
procedure library of support routines, and routines for loading the 
microcode and initializing the device. The system software and support 
routines provide a control path for synchronizing the use of buffers, 
specifying requests, and starting and stopping requests; the actual data 
algorithms for the laboratory data acquisition I/O devices are accomplished 
by the LPA11-K. 


The LPA11-K driver and the associated I/O interface have the following 


features: 
e They permit multiple LPA11-K subsystems on a single UNIBUS 
adapter. 


e¢ They operate as an integral part of the VMS operating system. 


¢ They can be loaded on a running VMS operating system without 
relinking the executive. 


e They handle I/O requests, function dispatching, UNIBUS adapter 
map allocation, interrupts, and error reporting for multiple LPA11-K 
subsystems. 


¢ The LPA11-K functions as a multibuffered device. Up to eight buffer 
areas can be defined per request. Up to eight requests can be handled 
simultaneously. Buffer areas can be reused after the data they contain 
is processed. 
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Because the LPA11-K chains buffer areas automatically, a start data 
transfer request can transfer an infinite and noninterrupted amount of 
data. 


Multiple ASTs are dynamically queued by the driver to indicate when 
a buffer has been filled (the data is available for processing) or emptied 
(the buffer is available for new data). 


The high-level language support routines have the following features: 


They translate arguments provided in the high-level language calls 
into the format required for the Queue I/O interface. 


They provide a buffer chaining capability for a multibuffering 
environment by maintaining queues of used, in use, and available 
buffers. 


They adhere to all VMS conventions for calling sequences, use of 
shareable resources, and reentrancy. 


They can be part of a resident global library, or they can be linked into 
a process image as needed. 


The routines for loading microcode and initializing devices have the 
following features: 


They execute, as separate processes, images that issue I/O requests. 
These I/O requests initiate microcode image loading, start the 
LPA11-K subsystem, and automatically configure the peripheral 
devices on the LPA11-K internal I/O bus. 


They can be executed at the request of the user or an operator. 
They can be executed at the request of other processes. 


They can be executed automatically when the system is initialized and 
on power recovery. 


Figure 4-1 shows the relationship of the supporting software to the 
LPA11-K. 
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Figure 4-1 Relationship of Supporting Software to LPA11-K 
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4.3 LPA11-K Device Information 


You can obtain information on all peripheral data acquisition devices 
on the LPA11-K internal I/O bus by using the Get Volume Information 
($GETDVI) system service. (See the VMS System Services Reference 
Manual.) 


$GETDVI returns device characteristics when you specify the item 
codes DVI$_DEVCHAR and DVI$_DEVDEPEND. Tables 4—2 and 4-3 
list these characteristics. The $DEVDEF macro defines the device- 
independent characteristics; the $LADEF macro defines the device- 
dependent characteristics. Device-dependent characteristics are set by 
the set clock, initialize, and load microcode I/O functions to any one of, or 
a combination of, the values listed in Table 4—3. 
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DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device 
type names, which are defined by the $DCDEF macro. The device class for 
the LPA11-K is DC$_REALTIME; the device type is DT$_LPA11. 
DVI$_DEVBUFSIZ is not applicable to the LPA11-K. 


Table 4-2 LPA11-K Device-Independent Characteristics 


Characteristic’ 


DEV$M_AVL 


DEV$M_IDV 

DEV$M_ODV 
DEV$M_RTM 
DEV$M_SHR 


Meaning 
Dynamic Bit (Conditionally Set) 


Device is online and available. 


Static Bits (Always Set) 


Device is capable of input. 
Device is capable of output. 
Device is real-time. 

Device is shareable. 


'Defined by the $DEVDEF macro. 


Table 4-3. LPA11-K Device-Dependent Characteristics 


Field’ 


LA$M_MCVALID 
LA$V_MCVALID 


LA$V_MCTYPE 
LA$S_MCTYPE 


Meaning 


The load microcode 1/O function (IO$_LOADMCODE) was 
performed successfully. LASM_MCVALID is set by 
1O$_LOADMCODE. Each microword is verified by reading it 
back and comparing it with the specified value. 
LA$M_MCVALID is cleared if there is no match. 


The microcode type, set by the load microcode I/O function 
(l1O$_LOADMCODE), is one of the following values: 


Value Meaning 


LA$K_MRMCODE Microcode type is in multirequest 


mode. 

LA$K_ADMCODE Microcode type is in dedicated A/D 
mode. 

LA$K_DAMCODE Microcode type is in dedicated D/A 
mode. 


‘Defined by the $LADEF macro. 


(continued on next page) 
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Table 4—3 (Cont.) LPA11-K Device-Dependent Characteristics 


Field’ 


LA$V_CONFIG 
LA$S_CONFIG 


LA$V_RATE 
LA$S_RATE 


Meaning 


The bit positions, set by the initialize 1/O function 
(IO$_INITIALIZE), for the peripheral data acquisition devices 
on the LPA11-K internal I/O bus are one or more of the 
following: 


Value Meaning 
LA$V_CLOCKA Clock A 
LA$M_CLOCKA 

LA$V_CLOCKB Clock B 
LA$M_CLOCKB 

LA$V_AD1 A/D device 1 
LA$M_AD1 

LA$V_AD2 A/D device 2 
LA$M_AD2 

LA$V_DA D/A device 1 
LA$M_DA 

LA$V_DIO1 Digital 1/O buffer 1 
LA$M_DIO1 

LA$V_DIO2 Digital /O buffer 2 
LA$M_DIO2 

LA$V_DIO3 Digital I/O buffer 3 
LA$M_DiO3 

LA$V_DIO4 Digital /O buffer 4 
LA$M_DIO4 

LA$V_DIO5 Digital I/O buffer 5 
LA$M_DIO5 


The Clock A rate, which is set by the set clock function 
(l1O$_SETCLOCK), is one of the following values: 


Value Meaning 


Stopped 

1 MHz 

100 kHz 

10 kHz 

1 kHz 

100 Hz 
Schmidt trigger 


NO oO fF WOM = CO 


Line frequency 





'Defined by the $LADEF macro. 


(continued on next page) 
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Table 4-3 (Cont.) LPA11-K Device-Dependent Characteristics 


Field’ Meaning 
LA$V_PRESET The Clock A preset value set by the set clock function 
LA$S_PRESET (l1O$_SETCLOCK). (The value is in two’s complement form in 


the range 0 through 65,535.) The clock rate divided by the 
clock preset value yields the clock overflow rate. 


1Defined by the $LADEF macro. 


LPA11-K Function Codes 


Load Microcode 
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The LPA11-K I/O functions are as follows: 
¢ Load the microcode into the LPA11-K. 
e Start the LPA11-K microprocessor. 
¢ Initialize the LPA11-K subsystem. 
e Set the LPA11-K real-time clock rate. 


e Start a data transfer request. 


The first three functions are normally performed by the loader process, not 
by the user’s data transfer program. See Section 4.5.21 for a description of 
the loader process interface. 


The Cancel I/O on Channel (SCANCEL) system service is used to abort 
data transfers. 


This I/O function resets the LPA11-K and loads an image of LPA11-K 
microcode. Physical I/O privilege is required. The following function code 
is provided: 


e JO$ LOADMCODE—Load microcode 


The load microcode function takes the following device- or function- 
dependent arguments: 


e P1—tThe starting virtual address of the microcode image that is to be 
loaded into the LPA11-K 


e¢ P2—The number of bytes (usually 2048) that are to be loaded 


¢ P3—The starting microprogram address (usually 0) in the LPA11-K 
that is to receive the microcode 


If any data transfer requests are active at the time a load microcode 
request is issued, the load request is rejected and SS$_DEVACTIVE is 
returned in the I/O status block. 
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Each microword is verified by comparing it with the specified value in 
memory. If all words match (the microcode was loaded successfully) 

the driver sets the microcode valid bit (LA$V_MCVALID) in the device- 
dependent characteristics longword (see Table 4—3). If there is no 

match, SS$_DATACHECK is returned in the I/O status block and 
LA$V_MCVALID is cleared to indicate that the microcode was not properly 
loaded. If the microcode was loaded successfully, the driver stores one of 
the microcode type values (LA$K_MRCODE, LA$K_ADCODE, or 
LA$K_DAMCODE) in the characteristics longword. 


After a load microcode function is completed, the second word of the I/O 
status block contains the number of bytes loaded. 


4.4.2 Start Microprocessor 


This I/O function resets the LPA11-K and starts (or restarts) the LPA11-K 
microprocessor. Physical I/O privilege is required. The following function 
code is provided: 


¢ JO$_STARTMPROC—Start microprocessor 


This function code takes no device- or function-dependent arguments. 


The start microprocessor function can return five error codes in the I/O 
status block (see Section 4.6): 


SS$_CTRLERR SS$_DEVACTIVE SS$_MCNOTVALID 
SS$_POWERFAIL SS$_TIMEOUT 


The LPA11-K Laboratory Peripheral Accelerator User’s Guide provides 
additional information on error codes. 


4.4.3 Initialize LPA11-K 


This I/O function issues a subsystem initialize command to the LPA11-K. 
This command specifies LPA11-K laboratory I/O device addresses and 
other table information for the subsystem. It is issued only once after 
restarting the subsystem and before any other LPA11-K command is given. 
Physical I/O privilege is required. The VMS operating system defines the 
following function code: 


¢ 10$_INITIALIZE—Initialize LPA11-K 


The initialize LPA11-K function takes the following device- or function- 
dependent arguments: 


¢ Pi—The starting, word-aligned, virtual address of the initialize 
command table in the user process. This table is read once by the 
LPA11-K during the execution of the initialize command. See the 
LPA11-K Laboratory Peripheral Accelerator User’s Guide for additional 
information. 


e 2—Length of the initialize command buffer (always 278 bytes). 
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Set Clock 
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Note: 


If the initialize function is completed successfully, the appropriate device 
configuration values are set in the device-dependent characteristics 
longword (see Table 4-3). 


The initialize function can return the following 10 error codes in the I/O 
status block: 


SS$_BUFNOTALIGN SS$_CANCEL $S$_CTRLERR 
SS$_DEVCMDERR SS$_INCLENGTH SS$_INSFMAPREG 
SS$_IVMODE SS$_MCNOTVALID SS$_POWERFAIL 
SS$_TIMEOUT 


If a device specified in the initialize command table is not in the 
LPA11-K configuration, an error condition (SS$_DEVCMDERR) occurs 
and the address of the first device not found is returned in the LPA11-K 
maintenance status register (see Section 4.6). A program can use this 
characteristic to poll the LPA11-K and determine the current device 
configuration. 


This virtual function issues a clock control command to the LPA11-K. The 
clock control command specifies information necessary to start, stop, or 
change the sample rate at which the real-time clock runs on the LPA11-K 
subsystem. 


If the LPA11-K has more than one user, caution should be 
exercised when the clock rate is changed. In multirequest mode, a 
change in the clock rate affects all users. 


The following function code is provided: 
e JO$_SETCLOCK—Set clock 


The set clock function takes the following device- or function-dependent 
arguments: 


¢ P2—Mode of operation. The VMS operating system defines the 
following clock start mode word (hexadecimal) values: 
Value Meaning 
1 KW11-K Clock A 
11 KW11-K Clock B 


¢ P3—Clock control and status. The VMS operating system defines the 
following clock status word (hexadecimal) values: 


Laboratory Peripheral Accelerator Driver 
4.4 LPA11-K Function Codes 


Value Meaning 


0 Stop clock 
143 1 MHz clock rate 
145 100 kHz clock rate 
147 10 kHz clock rate 
149 1 kHz clock rate 


14B 100 Hz clock rate 
14D Clock rate is Schmidt trigger 1 
14F Clock rate is line frequency 


e P4—The two’s complement of the real-time clock preset value. The 
range is 16 bits for the KW11-K Clock A and 8 bits for the KW11-K 
Clock B. 


The LPA11-K Laboratory Peripheral Accelerator User’s Guide describes the 
clock start mode word and the clock status word in greater detail. 


If the set clock function is completed successfully for Clock A, the clock 
rate and preset values are stored in the device-dependent characteristics 
longword (see Table 4—3). 


The set clock function can return six error codes in the I/O status block 
(see Section 4.6): 


SS$_CANCEL SS$_CTRLERR SS$_DEVCMDERR 
SS$_MCNOTVALID SS$_POWERFAIL SS$_TIMEOUT 


The LPA11-K Laboratory Peripheral Accelerator User’s Guide provides 
additional information on error codes. 


4.4.5 Start Data Transfer Request 


This virtual I/O function issues a data transfer start command that 
specifies the buffer addresses, sample mode, and sample parameters used 
by the LPA11-K. This information is passed to the data transfer command 
table. The following function code is provided: 


¢ [0$_ STARTDATA—Start data transfer request 


The start data transfer request function takes the following function 
modifier: 


¢ IO$M_SETEVF—Set event flag 


The start data transfer request function takes the following device- or 
function-dependent arguments: 


¢ P1—the starting virtual address of the data transfer command table 
in the user’s process. 


¢ P2—The length in bytes (always 40) of the data transfer command 
table. 
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e P3—The AST address of the normal buffer completion AST routine 
(optional). 


¢ P4—The AST address of the buffer overrun completion AST routine 
(optional). This argument is used only when the buffer overrun bit 
(LA$M_BFROVRN) is set, that is, when a buffer overrun condition is 
classified as a nonfatal error. 


A buffer overrun condition differs from a data overrun condition. The 
LPA11-K fetches data from, or stores data in, memory. If data cannot be 
fetched quickly enough (for example, when there is too much UNIBUS 
activity) a data underrun condition occurs. If data cannot be stored 
quickly enough, a data overrun condition occurs. After each buffer is filled 
or emptied, the LPA11-K obtains the index number of the next buffer to 
process from the user status word (USW). (See the LPA11-K Laboratory 
Peripheral Accelerator User’s Guide.) A buffer overrun condition occurs if 
the LPA11-K fills or empties buffers faster than the application program 
can supply new buffers. For example, buffer overrun can occur when the 
sampling rate is too high, the buffers are too small, or the system load is 
too heavy. 


The LPA11-K driver accesses the 10-longword data transfer command 
table, shown in Figure 4—2, when the data transfer start command is 
processed. After the command is accepted and data transfers begin, the 
driver does not access the table. 


In the first longword of the data transfer command table, the first two 
bytes contain the LPA11-K start data transfer request mode word. (The 
LPA11-K Laboratory Peripheral Accelerator User’s Guide describes the 
functions of this word.) 


The third byte contains the number (0-7) of the highest buffer available 
and the buffer overrun flag bit (bit 23; values: LA$M_BFROVRN and 
LA$V_BFROVRN). If this bit is set, a buffer overrun condition is a _ 
nonfatal error. 


The second longword contains the user status word address (see the 
LPA11-K Laboratory Peripheral Accelerator User’s Guide). This virtual 
address points to a two-byte area in the user-process space and must be 
word aligned. 


The third longword contains the size (in bytes) of the overall buffer area. 
The virtual address in the fourth longword is the beginning address of 
this area. This address must be longword aligned. The overall buffer area 
contains a specified number of buffers (the number of the highest available 
buffer specified in the first longword plus one). Individual buffers are 
subject to length restrictions: in multirequest mode the length must be in 
multiples of two bytes; in dedicated mode the length must be in multiples 
of four bytes. All data buffers are virtually contiguous for each data 
transfer request. 
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Figure 4-2 Data Transfer Command Table 
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The fifth and sixth longwords contain the random channel list (RCL) 
length and address, respectively. The RCL address must be word aligned. 
The last word in the RCL must have bit 15 set. (See the LPA11-K 
Laboratory Peripheral Accelerator User’s Guide for additional information 
on the RCL.) 


The seventh through tenth longwords contain LPA11-K-specific sample 
parameters. The driver passes these parameters directly to the LPA11-K. 
(See the LPA11-K Laboratory Peripheral Accelerator User’s Guide for a 
detailed description of their functions.) 
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The start data transfer request function can return the following 15 error 
codes in the I/O status block (see Section 4.6): 


SS$_ABORT SS$_BUFNOTALIGN SS$_CANCEL 
SS$_CTRLERR SS$_DEVCMDERR SS$_DEVREQERR 
SS$_EXQUOTA SS$_INCLENGTH SS$_INSFBUFDP 
SS$_INSFMAPREG SS$_INSFMEM SS$_MCNOTVALID 
SS$_PARITY SS$_POWERFAIL SS$_TIMEOUT 


Data buffers are chained and reused as the LPA11-K and the user process 
dispose of the data. As each buffer is filled or emptied, the LPA11-K driver 
notifies the application process either by setting the event flag specified by 
the QIO request efn argument or by queuing an AST. Since buffer use is 
a continuing process, the event flag is set or the AST is queued a number 
of times. The user process must clear the event flag (or receive the AST), 
process the data, and specify the next buffer for the LPA11-K to use. 


If the set event flag function modifier (IO$M_SETEVF) is specified, the 
event flag is set repeatedly: when the data transfer request is started, 
after each buffer completion, and when the request completes. If IO$M_ 
SETEVF is not specified, the event flag is set only when the request 
completes. 


ASTs are preferred over event flags for synchronizing a program with the 
LPA11-K, because AST delivery is a queued process, while the setting of 
event flags is not. If only event flags are used, buffer status may be lost. 


Three AST addresses can be specified. For normal data buffer transactions 
the AST address specified in the P3 argument is used. If the buffer 
overrun bit in the data transfer command table is set and an overrun 
condition occurs, the AST address specified in the P4 argument is used. 
The AST address specified in the astadr argument of the QIO request is 
used when the entire data transfer request is completed. The astprm 
argument specified in the QIO request is passed to all three AST routines. 


If insufficient dynamic memory is available to allocate an AST block, an 
error (SS$_INSFMEM) is returned. If the user does not have sufficient 
AST quota remaining to allocate an AST block, an error (SS$_EXQUOTA) 
is returned. In either case, the request is stopped. Normally, there are 
never more than three outstanding ASTs per LPA11-K request. 


4.4.6 LPA11-K Data Transfer Stop Command 
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The Cancel I/O on Channel ($CANCEL) system service is used to abort 
data transfers for a particular process. When the LPA11-K driver receives 
a $CANCEL request, a data transfer stop command is issued to the 
LPA11-K. 


To stop a data transfer, set bit 14 of the user status word. If this bit is 
set, the transfer stops at the end of the next buffer transaction (see the 
LPA11-K Laboratory Peripheral Accelerator User’s Guide). 
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4.5 High-Level Language Interface 


The VMS operating system supports several program-callable procedures 
that provide access to the LPA11-K. The formats of these calls are 
documented in this manual for VAX FORTRAN users. VAX MACRO users 
must set up a standard VMS argument block and issue the standard 
CALL procedure. (VAX MACRO users can also access the LPA11-K 
directly through the use of the device-specific QIO functions described 

in Section 4.4.) Users of other high-level languages must specify the 
proper subroutine or procedure invocation. 


4.5.1. High-Level Language Support Routines 


The VMS operating system provides 20 high-level language procedures for 


the LPA11-K. These procedures are divided into four classes. Table 4-4 
lists the classes and the VAX procedures for the LPA11-K. 


Table 4—4 VAX Procedures for the LPA11-K 


Class Subroutine Function 

Sweep Control LPASADSWP __ Start A/D converter sweep 
LPA$DASWP __ Start D/A converter sweep 
LPA$DISWP Start digital input sweep 
LPASDOSWP _ Start digital output sweep 
LPA$LAMSKS Specify LPA11-K controller and digital mask 

words 

LPASSETADC = Specify channel select parameters 
LPA$SSETIBF Specify buffer parameters 
LPASSTPSWP = Stop sweep 

Clock control LPA$CLOCKA _ Set Clock A rate 
LPASCLOCKB _ Set Clock B rate 
LPA$SXRATE Compute clock rate and preset value 

Data Butfer LPASIBFSTS Return buffer status 

Control LPASIGTBUF Return next available buffer 
LPASINXTBF Alter buffer order 
LPASIWTBUF Return next buffer or wait 
LPA$RLSBUF Release buffer to LPA11-K 
LPASRMVBUF Remove buffer from device queue 

Miscellaneous LPASCVADF Convert A/D input to floating point 
LPA$FLT16 Convert unsigned integer to floating point 
LPA$LOADMC _ Load microcode and initialize LPA11-K 
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Buffer Queue Control 


This section is provided for informational purposes only. 


Buffer queue control for data transfers by LPA11-K subroutines involves 
the use of the following queues: 


¢ Device queue (DVQ) 
¢ User queue (USQ) 
e In-use queue (IUQ) 


Each data transfer request can specify from one through eight data buffer 
areas. The user specifies these buffers by address. During execution of the 
request, the LPA11-K assigns an index from 0 through 7 when a buffer is 
referenced. 


The DVQ contains the indexes of all the buffers that the user has released 
(buffers made available to be filled or emptied by the LPA11-K). For output 
functions (D/A and digital output), these buffers contain data to be output 
by the LPA11-K. For input functions (A/D and digital input), these buffers 
are empty and waiting to be filled by the LPA11-K. 


The USQ contains the indexes of all buffers that are waiting to be returned 
to the user. The LPASIWTBUF and LPA$IGTBUF calls are used to return 
the index of the next buffer in the USQ. For output functions (D/A and 
digital output), these buffers are empty and waiting to be filled by the 
application program. For input functions (A/D and digital input), these 
buffers contain data to be processed by the application program. 


The IUQ contains the indexes of all buffers that are currently being 
processed by the LPA11-K. Normally, the I[UQ contains the indexes of the 
following buffers: 


¢ The buffer currently being filled or emptied by the LPA11-K 


¢ The next buffer to be filled or emptied by the LPA11-K. (This is the 
buffer specified by the next buffer index field in the user status word.) 


Because the LPA11-K driver requires that at least one buffer be ready 
when the input or output sweep is started, the user must call the 
LPA$RLSBUF subroutine before the sweep is initiated. 


Figure 4—3 shows the flow between the buffer queues. 


4.5.1.2 Subroutine Argument Usage 


Table 4—5 describes the general use of the subroutine arguments. The 
subroutine descriptions in the following sections contain additional 
information on argument usage. The (IBUF), (BUF), and (ICHN) (random 
channel list address) arguments must be aligned on specific boundaries. 
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Figure 4-3 Buffer Queue Control 
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Table 4—5 Subroutine Argument Usage 


Argument 


IBUF 


LBUF 


Meaning 


A 50-longword array initialized by the LPASSETIBF subroutine. IBUF is the impure area used by 
the buffer management subroutines. A unique IBUF array is required for each simultaneously 
active request. IBUF must be longword aligned. 


The first quadword in the IBUF array is an I/O status block (IOSB) for high-level language 
subroutines. The LPA$IGTBUF and LPASIWTBUF subroutines fill this quadword with the current 
and completion status (see Section 4.6). 


Specifies the size of each data buffer in words (must be even for dedicated mode sweeps). 

All buffers are the same size. The minimum value for LBUF is 6 for multirequest mode data 
transfers and 258 for dedicated mode data transfers. The aggregate size of the assigned buffers 
must be less than 32,768 words. Thus, the maximum size of each buffer (in words) is limited to 
32,768 divided by the number of buffers. The LBUF argument length is one word. 


(continued on next page) 
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Table 4—5 (Cont.) Subroutine Argument Usage 


Argument 


NBUF 


MODE 


IRATE 


IPRSET 


DWELL 


Meaning 


Specifies the number of times the buffers are to be filled during the life of the request. If 
0 (default) is specified, sampling is indefinite and must be stopped with the LPASSTPSWP 
subroutine. The NBUF argument length is one longword. . 


Specifies sampling options. MODE bit values are listed in the appropriate subroutine descriptions. 
The default is 0. MODE values can be added to specify several options. No options are mutually 
exclusive, although not all bits can be applicable at the same time. The MODE argument length 
is one word. 


Specifies the clock rate as follows: 


Value Meaning 


| 
_t 


Direct-coupled Schmidt trigger 1 (Clock A only) 
Clock B overflow or no rate 

1 MHz 

100 kHz 

10 kHz 

1 kHz 

100 Hz 

Schmidt trigger 

Line frequency 


NO OF FB WDM =| O 


The IRATE argument length is one longword. 


Specifies the hardware clock preset value. This value is the two’s complement of the desired 
number of clock ticks between clock interrupts. (The maximum value is 0, the two’s complement 
of 65,536.) IPRSET can be computed by the LPA$XRATE subroutine. The IPRSET argument 
length is one word. 


Specifies the number of hardware clock overflows between sample sequences in multirequest 
mode. For example, if DWELL is 20 and NCHN is 3, then after 20 clock overflows one channel 
is sampled on each of the next three successive overflows; no sampling occurs for the next 20 
clock overflows. This allows different users to use different sample rates with the same hardware 
clock overflow rate. In dedicated mode, the hardware clock overflow rate controls sampling and 
DWELL is not accessed. Default for DWELL is 1. The DWELL argument length is one word. 
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Table 4—5 (Cont.) Subroutine Argument Usage 


Argument 


IEFN 


LDELAY 


ICHN 


NCHN 


IND 


Meaning 


Specifies the event flag number or completion routine address. The selected event flag is set at 
the end of each buffer transaction. If IEFN is 0 (default), event flag 22 is used. 


IEFN can also specify the address of a completion routine. This routine is called by the buffer 
management routine when a buffer is available and when the request is terminated, either 
successfully or with an error. The standard VMS calling and return sequences are used. The 
completion routine is called from an AST routine and is therefore at AST level. 


If IEFN specifies the address of a completion routine, the program must call the LPA$IGTBUF 
subroutine to obtain the next buffer. If IEFN specifies an event flag, the program must call the 
LPA$IWTBUF subroutine to obtain the next buffer and must use the %VAL operator: 


, SVAL(3), (Event flag 3) 
, BERFULL, (Address of completion 
routine) 


The IEFN argument length is one longword. 


If multiple sweeps are initiated, they must use different event flags. The software does not 
enforce this policy. 


Event flag 23 is reserved for use by the LPASCLOCKA and LPA$CLOCKB subroutines. If either 
of these subroutines is included in the user program, event flag 23 cannot be used. Also, if IEFN 
is defaulted, event flag 22 cannot be used in the user program. 


Specifies the delay, in IRATE units, from the start event until the first sample is taken. The 
maximum value is 65,535; default is 1. The LDELAY argument length is one word. The LPA11-K 
supports the LDELAY argument in multirequest mode only. 


Specifies the number of the first /O channel to be sampled. Default is channel 0. The ICHN 
argument length is one byte. The channel number is not the same as the channel assigned to 
the device by the $ASSIGN system service. The LPA11-K uses the channel number to specify 
the multiplexer address of an A/D, D/A, or digital I/O device on the LPA11-K internal I/O bus. 


Specifies the number of I/O device channels to sample in a sample sequence. Default is 1. If 
the NCHN argument is 1, the single channel bit is set in the mode word of the start request 
descriptor array (RDA) when the sweep is started. The RDA contains the information needed 
by the LPA11-K for each command (see the LPA11-K Laboratory Peripheral Accelerator User's 
Guide). The NCHN argument length is one word. 


Receives the VMS success or failure code of the call. The IND argument length is one longword. 


LPASADSWP — Initiate Synchronous A/D Sampling Sweep 


The LPASADSWP subroutine initiates A/D sampling through an AD11-K. 
The format of the LPASADSWP subroutine call is as follows: 


CALL LPASADSWP. (IBUF,LBUF,[NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY],[ICHN}, [NCHN},[IND]) 
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Arguments are as described in Section 4.5.1.2, with the following 


additions: 
MODE 


IND 


Specifies sampling options. The VMS operating system defines the 
following sampling option values: 


Value Meaning 


32 Parallel A/D conversion sample algorithm is used if dual A/D 
converters are specified (value = 8192). Absence of this bit 
implies the serial A/D conversion sample algorithm. 


64 Multirequest mode request. Absence of this bit implies a 
dedicated mode request. 
512 External trigger (Schmidt trigger 1). Dedicated mode only. This 


value is used when a user-supplied external sweep trigger 

is desired. The external trigger is supplied by the KW11-K 
(Schmidt trigger 1 output) to the AD11-K (external start input). 
If MODE=512, the user process must specify a Clock A rate of 
—1 for proper A/D sampling. This is nonclock-driven sampling 
(see Section 4.5.10). (The LPA11-K Laboratory Peripheral 
Accelerator User’s Guide provides additional information on the 
use of external triggers.) 


1024 Time stamped sampling with Clock B. The double word consists 
of one data word followed by the value of the LPA11-K’s internal 
16-bit counter at the time of the sample (see the LPA11-K 
Laboratory Peripheral Accelerator User's Guide). Multirequest 
mode only. 


2048 Event marking. Multirequest mode only. (The LPA11-K 
Laboratory Peripheral Accelerator User’s Guide describes 
event marking.) 


4096 Start method. If selected, the digital input start method is used. 
If not selected, the immediate start method is used. Multirequest 
mode only. 


8192 Dual A/D converters are to be used. Dedicated mode only. 


16384 Buffer overrun is a nonfatal error. The LPA11-K will automatically 
default to fill buffer 0 if a buffer overrun condition occurs. 


If MODE is defaulted, A/D sampling starts immediately with absolute 
channel addressing in dedicated mode. The LPA11-K does not support 
delays in dedicated mode. 


Returns the success or failure status as follows: 


0 = Error in call. Possible causes are the following: LPA$SETIBF 
subroutine was not previously called; LPASRLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed by 
the LPA$SETIBF subroutine call. 


1 = successful sweep started 
nnn = VMS status code 
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4.5.3. LPA$S$DASWP — Initiate Synchronous D/A Sweep 
The LPA$DASWP subroutine initiates D/A output to an AA11-K. 
The format for the LPASDASWP subroutine call is as follows: 


CALL LPA$SDASWP (IBUF,LBUF,[NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY},[ICHN],[NCHN],[IND]) 


Arguments are as described in Section 4.5.1.2, with the following 
additions: 


MODE Specifies the sampling options. The VMS operating system defines the 
following start criteria values: 


Value Meaning 


0 Immediate start. This is the default value for MODE. 
64 Multirequest mode. If not selected, this request is for dedicated 
mode. 


4096 Start method. If selected, the digital input start method is used. 
If not selected, the immediate start method is used. Multirequest 
mode only. 


16384 Buffer overrun is a nonfatal error. The LPA11-K will automatically 
default to empty buffer O if a buffer overrun condition occurs. 


IND Returns the success or failure status as follows: 


0 = Error in call. Possible causes are the following: LPA$SETIBF 
subroutine was not previously called; LPASRLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed by 
the LPA$SETIBF subroutine call. 


1 = successful sweep started 
nnn = VMS status code 


4.5.4 LPA$DISWP — Initiate Synchronous Digital Input Sweep 


The LPA$DISWP subroutine initiates digital input through a DR11-K. It 
is applicable in multirequest mode only. 


The format of the LPA$DISWP subroutine call is as follows: 


CALL LPA$DISWP (IBUF,LBUF,NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY],[ICHN],[NCHN}, [IND]) 
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Arguments are as described in Section 4.5.1.2, with the following 


additions: 


MODE Specifies sampling options. The VMS operating system defines the 
following sampling option values: 


Value Meaning 

0 Immediate start. This is the default value for MODE. 

512 External trigger for DR11-K. (The LPA11-K Laboratory Peripheral 
Accelerator User’s Guide describes the use of external triggers.) 

1024 Time stamped sampling with Clock B. The double word 
consists of one data word followed by the value of the internal 
LPA11-K 16-bit counter at the time of the sample (see the 
LPA11-K Laboratory Peripheral Accelerator User’s Guide). 

2048 Event marking. (The LPA11-K Laboratory Peripheral Accelerator 
User's Guide describes event marking.) 

4096 Start method. If selected, the start method is digital input. If not 
selected, the start method is immediate. Multirequest mode only. 

16384 Buffer overrun is a nonfatal error. The LPA11-K will automatically 
default to fill buffer 0 if a buffer overrun condition occurs. 

IND Returns the success or failure status as follows: 


0 = Error in call. Possible causes are the following: LPASSETIBF 
subroutine was not previously called; LPASRLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed by 
the LPA$SETIBF subroutine call. 


1 = successful sweep started 


nnn = VMS status code 


4.5.5 LPAS$DOSWP — Initiate Synchronous Digital Output Sweep 


The LPA$DOSWP subroutine initiates digital output through a DR11-K. It 
is applicable in multirequest mode only. 


The format of the LPA$DOSWP subroutine call is as follows: 


CALL LPA$DOSWP (IBUF,LBUF[NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY],[ICHN],[NCHN],[IND]) 
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Arguments are as described in Section 4.5.1.2, plus the following: 


MODE Specifies sampling options. The VMS operating system defines the 
following values: 


Value Meaning 


0 Immediate start. This is the default value for MODE. 


512 External trigger for DR11-K. (The LPA11-K Laboratory Peripheral 
Accelerator User's Guide describes the use of external triggers.) 


4096 Start method. If selected, digital input start. If not selected, 
immediate start. 


16384 Buffer overrun is a nonfatal error. The LPA11-K will automatically 
default to empty buffer 0 if a buffer overrun condition occurs. 


IND Returns the success or failure status as follows: 


0 = Error in call. Possible causes are the following: LPASSETIBF 
subroutine was not previously called; LPASRLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed by 
the LPA$SETIBF subroutine call. 


1 = successful sweep started 
nnn = VMS status code 


LPA$SLAMSKS — Set LPA11-K Masks and NUM Buffer 


The LPA$LAMSKS subroutine initializes a user buffer that contains a 
number to append to the logical name LPA11$, a digital start word mask, 
an event mark mask, and channel numbers for the two masks. 


The LPA$LAMSKS subroutine must be called in the following cases: 

¢ Ifusers intend to use digital input starting or event marking 

¢ Ifusers do not want to use the default of LAAO assigned to LPA11$0 
¢ If multiple LPA11-Ks are used 


The format of the LPA$LAMSKS subroutine call is as follows: 
CALL LPA$LAMSKS (LAMSKB,[NUM],[IUNIT], [IDSC], [IEMC],[IDSW],[IEMW},[IND]) 


Argument descriptions are as follows: 


LAMSKB Specifies a four-word array. 

NUM Specifies the number appended to LPA11$. The sweep is started on 
the LPA11-K assigned to LPA11$num. 

IUNIT Not used. This argument is present for compatibility only. 

IDSC Specifies the digital START word channel. Range is 0 through 4. 
The IDSC argument length is one byte. 

IEMC Specifies the event MARK word channel. Range is 0 through 4. The 
IEMC argument length is one byte. 

IDSW Specifies the digital START word mask. The IDSW argument length 
is one word. 
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IEMW Specifies the event MARK word mask. The IEMW argument length 
is one word. 
IND Always equal to 1 (success). This argument is present for 


compatibility only. 


4.5.7 | LPASSETADC — Set Channel Information for Sweeps 


The LPA$SETADC subroutine establishes channel start and increment 
information for the sweep control subroutines (see Table 4—4). It must be 
called to initialize IBUF before the LPA$SETADC subroutine is called. 


The LPA$SETADC subroutine can be called in either of the following 
formats: 


CALL LPA$SETADC (IBUF[IFLAG],[ICHN],[NCHN],[INC],[IND]) 
or 

IND=LPA$SETADC (IBUF[IFLAG],[ICHN],[NCHN],[INC}) 
Argument descriptions are as follows: 


IND Returns the success or failure status as follows: 
0 = LPA$SETIBF was not called prior to the LPASSETADC call 
1 = LPA$SSETADC call successful 


IBUF The IBUF array specified in the LPA$SETIBF call. 
IFLAG Reserved. This argument is present for compatibility only. 
ICHN Specifies the first channel number. Range is 0 through 255; default 


is 0. The ICHN argument length is one longword. 


lf INC = 0, ICHN is the address of a random channel list. This 
address must be word aligned. 


NCHN Specifies the number of samples taken per sample sequence. 
Default is 1. 
INC Specifies the channel increment. Default is 1. If INC is 0, ICHN is 


the address of a random channel list. The INC argument length is 
one longword. 


4.5.8 LPA$SETIBF — Set IBUF Array for Sweeps 
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The LPA$SETIBF subroutine initializes the IBUF array for use with the 
following subroutines: 


LPASADSWP LPASDASWP LPA$SDISWP 
LPASDOSWP LPASIBFSTS LPASIGTBUF 
LPASINXTBF LPASIWTBUF LPASRLSBUF 
LPASRMVBUF LPASSETADC LPASSTPSWP 


The format of the LPA$SETIBF subroutine call is as follows: 
CALL LPA$SETIBF (IBUF{IND],[LAMSKB],BUFO,[BUF1....,BUF7]) 
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Arguments are as described in Section 4.5.1.2, with the following 
additions: 


IBUF Specifies a 50-longword array that is initialized by this subroutine. 
IBUF must be longword-aligned. (See Table 4—5 for additional 
information on !BUF.) 


IND Returns the success or failure status as follows: 


0 = Error in call. Possible causes are the following: incorrect number 
of arguments; IBUF array not longword-aligned; buffer addresses not 
equidistant. 


1 = IBUF initialized successfully 


LAMSKB Specifies the name of a four-word array. This array allows the use of 
multiple LPA11-Ks within the same program because the argument 
used to start the sweep is specified by the LPASLAMSKS subroutine 
call. (See Section 4.5.6 for a description of the LPASLAMSKS 
subroutine.) 


BUFO, ... Specify the names of the buffers. A maximum of eight buffers can 
be specified. At least two buffers must be specified to provide 
continuous sampling. The LPA11-K driver requires that all buffers 
be contiguous. To ensure this, the LPASSETIBF subroutine verifies 
that all buffer addresses are equidistant. Buffers must be longword- 
aligned. 


LPA$STPSWP — Stop In-Progress Sweep 


The LPA$STPSWP subroutine allows you to stop a sweep that is in 
progress. 


The format of the LPASSTPSWP subroutine call is as follows: 
CALL LPA$STPSWP (IBUF,{IWHEN},[IND]) 


Arguments are as described in Section 4.5.1.2, with the following 
additions: 


IBUF The IBUF array specified in the LPASADSWP, LPASDASWP, 
LPA$DISWP, or LPASDOSWP subroutine call that initiated the 
sweep. 

IWHEN Specifies when to stop the sweep. The VMS operating system 


defines the following values: 


0 = Abort sweep immediately. Uses the $CANCEL system service. 
This is the default sweep stop. 


1 = Stop sweep when the current buffer transaction is completed. 
(This is the preferred way to stop requests.) 


IND Receives a success or failure code in the standard VMS format: 

1 = Success 

nnn = VMS error code issued by the $CANCEL system service 
Note that when the LPA$STPSWP subroutine is returned, the sweep 
cannot, be stopped. If it is necessary to wait until the sweep has stopped, 


you can call the LPA$SIWTBUF subroutine in a loop until it returns 
IBUFNO = -1 (see Section 4.5.16). 
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4.5.10 LPA$CLOCKA — Clock A Conirol 


4.5.11 


The LPA$CLOCKA subroutine sets the clock rate for Clock A. 
The format of the LPA$CLOCKA subroutine call is as follows: 
CALL LPA$CLOCKA (IRATE,IPRSET,[IND],[NUM]) 
Arguments are as described in Section 4.5.1.2, with the following 
additions: 
IRATE Specifies the clock rate. One of the following values must be 
specified: 
Value Meaning 
—1 Direct-coupled Schmidt trigger 1. Used only for A/D 


sweeps in dedicated mode, that is, MODE = 512 (see 
Section 4.5.2). 


Clock B overflow or no rate 
1 MHz 

100 kHz 

10 kHz 

1 kHz 

100 Hz 

Schmidt trigger 1 


N OO Bh © NM = O 


Line frequency 


IPRSET Specifies the clock preset value. Maximum of 16 bits. The 
LPA$SXRATE subroutine can be used to calculate this value. The 
clock rate divided by the clock preset value yields the clock overflow 
rate. 

IND Receives a success or failure code as follows: 

1 = Clock A set successfully 
nnn = VMS error code indicating an I/O error 
NUM Specifies the number to be appended to the logical name LPA11$. 


The default value is 0. This subroutine sets Clock A on the LPA11-K 
assigned to LPA11$num. 


LPASCLOCKB — Clock B Control 
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The LPA$CLOCKB subroutine provides the user with control of the 
KW11-K Clock B. 


The format of the LPA$CLOCKB subroutine call is as follows: 
CALL LPA$CLOCKB ([IRATE],IPRSET,MODE,[IND],[NUM]) 
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Arguments are as described in Section 4.5.1.2, with the following 


additions: 


IRATE 


IPRSET 


MODE 


IND 


NUM 


Specifies the clock rate. One of the following must be specified: 


Value Meaning 


Stops Clock B 

1 MHz 

100 kHz 

10 kHz 

1 kHz 

100 Hz 

Schmidt trigger 3 
Line frequency 


N OO ff WO NM + O 


If IRATE is 0 (default), the clock is stopped and the IPRSET and 
MODE arguments are ignored. 


Specifies the preset value by which the clock rate is divided to yield 
the overflow rate. Maximum of eight bits. Overflow events can be 
used to drive Clock A. The LPA$XRATE subroutine can be used to 
calculate the IPRSET value. 


Specifies options. The VMS operating system defines the following: 
1 = Clock B operates in noninterrupt mode. 


2 = The feed B to A bit in the Clock B status register will be set (see 
the LPA11-K Laboratory Peripheral Accelerator User’s Guide). 


Receives a success or failure code as follows: 
1 = Clock B set successfully 
nnn = VMS error code indicating an {/O error 


Specifies the number to be appended to the logical name LPA11$. 
The default value is 0. This subroutine sets Clock B on the LPA11-K 
assigned to LPA11$num. 


4.5.12 LPAS$XRATE — Compute Clock Rate and Preset Value 


The LPA$XRATE subroutine computes the clock rate and preset value 
for the LPA$CLOCKA and LPA$CLOCKB subroutines using the specified 
intersample interval (AINTRVL). 


The LPA$XRATE subroutine can be called in either of the following 


formats: 


CALL LPA$XRATE (AINTRVL,IRATE,IPRSET,IFLAG) 
ACTUAL=LPA$XRATE(AINTRVL,IRATE,IPRSET,IFLAG) 
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Arguments are as described in Section 4.5.1.2, with the following 


additions: 
AINTRVL 


IRATE 
IPRSET 
IFLAG 


ACTUAL 


Specifies the intersample time selected by the user. The time is 
expressed in decimal seconds. Data type is floating point. 


Receives the computed clock rate as a value from 1 through 5. 
Receives the computed clock preset value. 


If the computation is for Clock A, IFLAG is 0; if for Clock B, IFLAG 
is not O (the maximum preset value is 255). The IFLAG argument 
length is one byte. 


Receives the actual intersample time if called as a function. Data 
type is floating point. If there are truncation and round-off errors, 
the resulting intersample time can be different from the specified 
intersample time. Note that when the LPASXRATE subroutine is 
called from VAX FORTRAN IV-PLUS programs as a function, it must 
be explicitly declared a real function. Otherwise, the LPASXRATE 
subroutine defaults to an integer function. 


If AINTRVL is either too large or too small to be achieved, both IRATE 
and ACTUAL are returned to 0. 


4.5.13 LPAS$IBFSTS — Return Buffer Status 
The LPA$IBFSTS subroutine returns information on the buffers used in a 


sweep. 


The format of the LPA$IBFSTS subroutine call is as follows: 
CALL LPA$IBFSTS (IBUF,ISTAT) 


Argument descriptions are as follows: 


IBUF 
ISTAT 


The IBUF array specified in the call that initiated the sweep. 


Specifies a longword array with as many elements as there are 
buffers involved in the sweep (maximum of eight). LPASIBFSTS fills 
each array element with the status of the corresponding buffer: 

+2 = Buffer in device queue. LPASRLSBUF has been called for this 
buffer. 


+1 = Buffer in user queue. The LPA11-K has filled (data input) or 
emptied (data output) this buffer. 


0 = Buffer is not in any queue. 


—1 = Buffer is in the in-use queue; that is, it is either being filled or 
emptied, or it is the next to be filled or emptied by the LPA11-K. 


4.5.14 LPA$SIGTBUF — Return Buffer Number 


The LPA$IGTBUF subroutine returns the number of the next buffer to be 
processed by the application program, the buffer at the head of the user 
queue (see Figure 4-3). It should be called by a completion routine 
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at AST level to determine the next buffer to process. If an event flag was 
specified in the start sweep call, the LPASIWTBUF, not the LPA$SIGTBUF 


subroutine, should be called. 

The LPA$IGTBUF subroutine can be called in one of these formats: 
CALL LPASIGTBUF (IBUF,IBUFNO) 

IBUFNO=LPA$IGTBUF(IBUF) 

Arguments are as described in Section 4.5.1.2, plus the following: 


IBUF The IBUF array specified in the call that initiated the sweep. 


IBUFNO Returns the number of the next buffer to be filled or emptied by the 
application program. 


Table 4—6 lists the possible combinations of IBUFNO and IOSB contents 
on the return from a call to the LPASIGTBUF subroutine. The first four 
words of the IBUF array contain the I/O status block (IOSB). If IBUFNO 
is —1, the IOSB must be checked to determine the reason. 


Table 4-6 LPAS$IGTBUF Call — IBUFNO and IOSB Contents 


IBUFNO 1OSB(1) 


n 0 
—1 0 
—1 
—-1 VMS 

error 
code 


1IOSB(2) 1OSB(3),(4) Meaning 
(byte 0 Normal buffer complete. 
count) 
0 0 No buffers in queue. Request still active. 
0 0 No buffers in queue. Sweep terminated 
normally. 
0 LPA11-K ready-out and No buffers in queue. Sweep terminated due 
maintenance registers to error condition. Section 4.6 describes the 
(only if SSEDEVREQERR, VMS error codes; the LPA11-K Laboratory 
SS$_CTRLERR, or Peripheral Accelerator User’s Guide lists 
SS$DEVCMDERR is — the LPA11-K error codes. 
returned) 


LPASINXTBF — Set Next Buffer to Use 


The LPA$INXTBF subroutine alters the normal buffer selection algorithm 
so that you can specify the next buffer to be filled or emptied. The specified 
buffer is reinserted at the head of the device queue. 


The LPA$INXTBF subroutine can be called in one of these formats: 
CALL LPA$INXTBF (IBUF,IBUFNO,IND) 
IND=LPA$INXTBF(IBUF, IBUFNO) 
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Arguments are as described in Section 4.5.1.2, plus the following: 


IBUF The IBUF array specified in the call that initiated the sweep. 

IBUFNO Specifies the number of the next buffer to be filled or emptied. The 
buffer must already be in the device queue. 

IND Returns the result of the call as follows: 


0 = Specified buffer not in the device queue 
1 = Next buffer successfully set 


4.5.16 LPAS$IWTBUF — Return Next Buffer or Wait 


The LPA$IWTBUF subroutine returns the next buffer to be processed by 
the application program, the buffer at the head of the user queue. If the 
user queue is empty, the LPASIWTBUF subroutine waits until a buffer is 
available. If a completion routine was specified in the call that initiated 

the sweep, LPA$IGTBUF, not LPA$SIWTBUF, should be called. 


The LPA$IWTBUF subroutine can be called in either of the following 
formats: 


CALL LPASIWTBUF (iBUF,[IEFN],IBUFNO) 
IBUFNO=LPA$IWTBUF(IBUF,[IEFN}) 


Arguments are as described in Section 4.5.1.2, with the following 
additions: 


IBUF The IBUF array specified in the call that initiated the sweep. 

IEFN Not used. This argument provides compatibility with the operating 
system. (The event flag is the one specified in the start sweep call.) 

IBUFNO Returns the number of the next buffer to be filled or emptied by the 


application program. 


Table 4—7 lists the possible combinations of IBUFNO and I/O status block 
contents on the return from a call to the LPA$IWTBUF subroutine. The 
first four words of the IBUF array contain the I/O status block. If IBUFNO 
is —1, the I/O status block must be checked to determine the reason. 


Table 4—7 LPA$IWTBUF Cail — IBUFNO and IOSB Contents 


IBUFNO IOSB(1) 


n 0 
—1 1 
— VMS 

error 
code 
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IOSB(2) IOSB(3),(4) Meaning 
(byte 0 Normal buffer complete. 
count) 
0 0 No buffers in queue. Sweep terminated 
normally. 
0 LPA11-K ready-out and No buffers in queue. Sweep terminated due 
maintenance registers to error condition. Section 4.6 describes the 
(only if SS$_DEVREQERR VMS error codes; the LPA11-K Laboratory 
SS$_CTRLERR, or SS$_ Peripheral Accelerator User’s Guide lists 


DEVCMDERR is returned) the LPA11-K error codes. 
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4.5.17 LPASRLSBUF — Release Data Buffer 


The LPA$RLSBUF subroutine declares one or more buffers available to 
be filled or emptied by the LPA11-K. It inserts the buffer at the tail of the 
device queue (see Figure 4-3). 


The format of the LPASRLSBUF subroutine call is as follows: 
CALL LPA$RLSBUF (IBUFIND], INDEXO,INDEX1.,...,INDEXN) 
Arguments are as described in Section 4.5.1.2, with the following 


additions: 
IBUF The IBUF array specified in the call that initiated the sweep. 
IND Returns the success or failure status as follows: 


0 = Buffer number was illegal, the number of arguments specified 
was incomplete, or a double buffer overrun occurred. A double 
buffer overrun can occur only if buffer overrun was specified as 
a nonfatal error, a buffer overrun occurs, and buffer 0 was not 
released (probably on the user queue after a previous buffer 
overrun). 

1 = Buffer(s) released successfully. 


INDEXO, ... Specify the indexes (0-7) of the buffers to be released. A 
maximum of eight indexes can be specified. 


The LPA$RLSBUF subroutine must be called to release a buffer 

(or buffers) to the device queue before the sweep is initiated. (See 
Section 4.5.1.1 for a discussion of buffer management.) Note that the 
LPA$RLSBUF subroutine does not verify whether the specified buffers are 
already in a queue. Ifa buffer is released when it is already in a queue, 
the queue pointers are invalidated and unpredictable results can occur. 


If buffer overrun is specified as a nonfatal error, buffer 0 should not be 
released before the sweep is initiated. However, if either the LPASIGTBUF 
or LPA$SIWTBUF subroutine returns buffer 0, it should be released. In 
this case, buffer 0 is set aside (not placed on a queue) until the buffer 
overrun occurs. If a buffer overrun occurs and buffer 0 was not released, 
the LPA$RLSBUF subroutine returns an error the next time buffer 0 is 
released. 


4.5.18 LPASRMVBUF — Remove Buffer from Device Queue 
The LPA$RMVBUF subroutine removes a buffer from the device queue. 
The format of the LPASRMVBUF subroutine call is as follows: 
CALL LPA$RMVBUF (IBUF,IBUFNO,[IND]) 
Arguments are as described in Section 4.5.1.2, with the following 


additions: 
IBUF The IBUF array specified in the call that initiated the sweep. 
IBUFNO Specifies the number of the buffer to remove from the device queue. 
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IND Returns the success or failure status as follows: 
O = Buffer not found in the device queue 
1 = Buffer successfully removed from the device queue 


4.5.19 LPA$CVADF — Convert A/D Input to Floating-Point 


The LPA$CVADF subroutine converts A/D input values to floating-point 
numbers. It is supported to provide compatibility with the VMS operating 
system. 


The LPA$CVADF subroutine can be called in either of the following 
formats: 


CALL LPASCVADF (IVAL,VAL) 
VAL=LPA$CVADF(IVAL) 


Argument descriptions are as follows: 


IVAL Contains the value (bits 11:0) read from the A/D input. Bits 15:12 
are 0. 
VAL Receives the floating-point value. 


4.5.20 LPA$FLT16 — Convert Unsigned 16-Bit Integer to Floating-Point 


4.5.21 


The LPA$FLP16 subroutine converts unsigned 16-bit integers to floating 
point. It is supported to provide compatibility with the VMS operating 
system. 


The LPA$FLT16 subroutine can be called in either of the following 
formats: 


CALL LPA$FLT16 (IVAL,VAL) 
VAL=LPA$FLT16(IVAL) 
Argument descriptions are as follows: 


IVAL An unsigned 16-bit integer. 
VAL Receives the converted value. 


LPA$LOADMC — Load Microcode and Initialize LPA11-K 
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The LPA$LOADMC subroutine provides a program interface to the 
LPA11-K microcode loader. It sends a load request through a mailbox 
to the loader process to load microcode and to initialize an LPA11-K. 
(Section 4.7.1 describes the microcode loader process.) 


The format of the LPASLOADMC subroutine call is as follows: 
CALL LPA$LOADMC ({ITYPE][,NUM][, IND][,IERROR]) 


4.6 


I/O Status Block 
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Argument descriptions are as follows: 


ITYPE The type of microcode to be loaded. The VMS operating system 
defines the following values: 


Value Meaning 


1 Multirequest mode; default value 
2 Dedicated A/D mode 
3 Dedicated D/A mode 
NUM The number to be appended to the logical name LPA11$. The 


default value is 0. 

IND Receives the completion status as follows: 
1 = Microcode loaded successfully 
nnn = VMS error code 


IERROR Provides additional error information. Receives the second longword 
of the I/O status block if SS$_CTRLERR, SS$_DEVCMDERR, or 
SS$_DEVREQERR is returned in IND. Otherwise, the contents of 
IERROR are undefined. 





The I/O status block (IOSB) format for the load microcode, start 
microprocessor, initialize LPA11-K, set clock, and start data transfer 
request QIO functions is shown in Figure 4—4. 


Figure 4—4 1/O Functions IOSB Content 


31 16 15 0 


LPA11-K 
Maintenance Status LPA11-K Ready—Out 


ZK-0662-GE 





VMS status values and the byte count are returned in the first longword. 
Status values are defined by the $SSDEF macro. The byte count is the 
number of bytes transferred by a IO$_ LOADMCODE request. If 
SS$_CTRLERR, SS$_DEVCMDERR, or SS$_DEVREQERR is returned 
in the status word, the second longword contains the LPA11-K ready- 
out register and LPA11-K maintenance status register values present at 
the completion of the request. The high byte of the ready-out register 
contains the specific LPA11-K error code (see the LPA11-K Laboratory 
Peripheral Accelerator User’s Guide). Appendix A of this manual lists the 
status returns for LPA11-K I/O functions. (The VMS System Messages 
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and Recovery Procedures Reference Manual provides explanations and 
suggested user actions for these returns.) 


If high-level language library procedures are used, the status returns 
listed in Appendix A can be returned from the resultant QIO functions. 
Since buffers are filled by these procedures asynchronously, two I/O status 
blocks are provided in the IBUF array: one for the high-level language 
procedures and one for the LPA11-K driver. The first four words of the 
IBUF array contain the I/O status block for the high-level language 
procedures. 


4.7 Loading LPA11-K Microcode 


The microcode loading and device initialization routines automatically 
load microcode during system initialization (if specified in the system 

manager’s startup file) and during power recovery. These routines also 
allow a nonprivileged user to load microcode and to restart the system. 


The LPA11-K loader and initialization routines consist of the following 
parts: 


¢ A microcode loader process that loads any of the three microcode 
versions, initializes the LPA11-K, and sets the clock rate. Loading is 
initiated by either a mailbox request or a power recovery AST. This 
process requires permanent mailbox (PRMMBX) and physical I/O 
privileges. 


e An operator process that accepts operator commands or indirect file 
commands to load microcode and to initialize an LPA11-K. This process 
uses a mailbox to send a load request to the loader process; temporary 
mailbox (TMPMBX) privilege is required. 


e An LPA1I-K procedure library routine that provides a program 
interface to the LPA11-K microcode loader. The procedure sends a 
load request through a mailbox to the loader process to load microcode 
and to initialize an LPA11-K. Section 4.5.21 describes that routine in 
greater detail. 


4.7.1 Microcode Loader Process 
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The microcode loader process loads microcode, initializes a specific 
LPA11-K, and sets the clock at the default rate (10 kHz interrupt rate). A 
bit set in a controller bit map indicates that the specified controller was 
loaded. The process specifies a power recovery AST, creates a mailbox 
whose name (LPA$LOADER) is entered in the system logical name table, 
and then hibernates. 


The correct device configuration is determined automatically. When 
LPA11-K initialization is performed, every possible device (see Table 4—1) 
is specified as present on the LPA11-K. If the LPA11-K returns a “device 
not found” error, the LPA11-K is reinitialized with that device omitted. 


4.7.2 
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On receipt of a power recovery AST, the loader process examines the 
controller bit map to determine which LPA11-Ks have been loaded. For 
each LPA11-K, the loader process performs the following functions: 


e Obtains device characteristics 
¢ Reloads the microcode previously loaded 
e Reinitializes the LPA11-K 


e Sets Clock A to the previous rate and preset value 


Operator Process 


The operator process loads microcode and initializes an LPA11-K through 
either terminal or indirect file commands. To run the operator process, 
type RUN SYS$SYSTEM:LALOAD. The command input syntax is as 
follows: 


devname/type 


In the preceding example, deuname is the device name of the LPA11-K 
to be loaded. A logical name can be specified. However, only one level of 
logical name translation is performed. If deuname is omitted, LAAO is the 
default name. If /type appears, it specifies one of the following types of 
microcode to load: 


¢ /MULTI_LREQUEST—Multirequest mode 
e /ANALOG_DIGITAL—Dedicated A/D mode 
¢ /DIGITAL_ANALOG—Dedicated D/A mode 


If /type type is omitted, /MULTI_LREQUEST is the default. 


After receiving the command, the operator process formats a message and 
sends it to the loader process. Completion status is returned through a 
return mailbox. 


RSX—11M/M—PLUS and VMS Differences 


General 


This section lists those areas of the VMS high-level language support 
routines that differ from the RSX—-11M LPA11-K routines. The 
RSX-11M/M-—PLUS I/O Drivers Reference Manual provides a detailed 
description of the RSX-11M LPA11-K support routines. Differences 
between the VMS and RSX-11M/M-PLUS routines can be determined 
by comparing the descriptions in the RSX-11M/M-PLUS I/O Drivers 
Reference Manual with the descriptions for the VMS routines in the 
preceding sections of this chapter. 


The following are general features of VMS high-level support routines: 


¢ The LUN argument is not used. The NUM argument specifies the 
number to be appended to the logical name LPA11$. 
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e All routine names have the prefix LPA$. 


e In the LPA$SETIBF routine, buffer addresses are checked for 
contiguity. 


¢ In the LPA$LAMSKS routine, the IUNIT argument is not used. 


¢ In the LPA$SIWTBUF routine, the IEFN argument is not used. The 
event flag specified in the sweep routine is used. 


¢ The combinations of IBUFNO and I/O status block (IOSB) values 
returned by the LPA$SIWTBUF and LPA$IGTBUF subroutines are 
different. 


4.8.2 Alignment and Length 


The following are features of alignment and length in VMS high-level 
support routines: 


¢ Buffers must be contiguous. 

¢ Buffers must be longword-aligned. 

¢ The random channel list (RCL) must be word-aligned. 

¢ The IBUF array length is 50 longwords and must be longword-aligned. 


4.8.3 Status Returns 


The following are features of status returns in VMS high-level support 
routines: 


¢ The I/O status block (IOSB) length is eight bytes; numeric values of 
errors differ. 


¢ Several routines return the following: 
1 = Success 
0 = Failure detected in support routine 


nnn = VMS status code; failure detected in system service 


4.8.4 Sweep Routines 


The following are features of sweep routines in VMS high-level support 
routines: 


¢ Ifan event flag is specified, it must be within a %2VAL( ) construction. 


¢ A tenth argument, IND, is added to return the success or failure 
status. 
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4.9 LPA11-K Programming Examples 


The following programming examples use LPA11-K high-level language 
procedures and LPA11-K Queue I/O functions. 


The VMS Device Support Manual volume contains information that is 
applicable to LPA11-K programming. 


4.9.1 LPA11-K High-Level Language Program (Program A) 


This sample program (Example 4—1) is an example of how the LPA11-K 
high-level language procedures perform an A/D sweep using three buffers. 
The program uses default arguments whenever possible to illustrate 

the simplest possible calls. The program assumes that dedicated mode 
microcode has previously been loaded into the LPA11-K. Table 4-8 lists 
the variables used in this program. 


Table 4-8 Program A Variables 


Variable Description 

BUFFER The data buffer array. BUFFER is a common area to guarantee 
longword alignment. 

IBUF The LPA11-K high-level language procedures use the IBUF array for 
local storage. 

BUFNUM BUFNUM contains the buffer number returned by LPASIWTBUF. In 


this example, the possible values are 0, 1, and 2. 
ISTAT ISTAT contains the status return from the high-level language calls. 


Example 4—1 LPA11-K High-Level Language Program (Program A) 

Cc KKKKEKKKKKKKKKK KKK KKK KKK KKK KKK KKK KEK RK KKK KKK KKK KKKKKKEKKKKKKKEKKKEKEK 
C 

C PROGRAM A 

fe 

Cc KREKKEKKKEKEEKKKKEKR KKK KE KRKEKKKKE KE KKK KEK KKK KRKEKREKKEKEKEKKERKEKRKKRKEKKRKEKKEKEKKKEEKEEESE 


INTEGER*2 BUFFER (1000, 0:2) , IOSB (4) 
INTEGER* 4 IBUF (50), ISTAT, BUFNUM 


COMMON /AREA1/BUFFER 
EQUIVALENCE (IOSB (1), IBUF (1) ) 


(continued on next page) 
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Example 4—1 (Cont.) LPA11-K High-Level Language Program (Program A) 





Cc 
C Set clock rate to 1 khz, clock preset to -10. 
Cc 


CALL LPASCLOCKA (4,-10,ISTAT) 
IF (.NOT. ISTAT) GO TO 950 


Cc 
C Initialize IBUF array for sweep. 
GC 
CALL LPASSETIBF (IBUF, ISTAT, , BUFFER(1,0),BUFFER(1,1),BUFFER (1,2) ) 
IF (.NOT. ISTAT) GO TO 950 
Cc 
C Release all the buffers. Note use of buffer numbers rather than 
C buffer names. 
Cc 
CALL LPASRLSBUF (IBUF, ISTAT,0,1,2) 
IF (.NOT. ISTAT) GO TO 950 
Cc 
C Start A/D sweep 
Cc 
CALL LPASADSWP (IBUF,1000,50,,,,,,,LSTAT) 
IF (.NOT. ISTAT) GO TO 950 
Cc 
C Get next buffer filled with data. If BUFNUM is negative, there 
C are no more buffers and the sweep is stopped. 
Cc 
100 BUFNUM = LPASIWTBUF (IBUF) 
IF (BUFNUM .LT. 0) GO TO 800 
Cc 


C Process data in buffer (1,BUFNUM) to buffer (1000,BUFNUM). 


(Application-dependent code is inserted at this point.) 


C Release buffer is filled again. 


Cc 
200 CALL LPASRLSBUF (IBUF, ISTAT, BUFNUM) 
IF (.NOT. ISTAT) GO TO 950 
GO TO 100 
Cc 
C There are no more buffers to process. Check to ensure that the 
C sweep ended successfully. IOSB(1) contains either 1 or a 
C VMS status code. 
Cc 
800 IF (.NOT. IOSB(1)) CALL LIBSSTOP (SVAL(IOSB(1) )) 
PRINT *,’SUCCESSFUL COMPLETION’ 
GO TO 2000 
Cc 
C Error return from subroutine. ISTAT contains either 0 ora 
C VMS error code. 
C 





(continued on next page) 
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Example 4—1 (Cont.) LPA11-K High-Level Language Program (Program A) 


950 IF (ISTAT .NE. 0) CALL LIBSSTOP (%VAL(ISTAT) ) 
PRINT *, ‘ERROR IN LPA11-K SUBROUTINE CALL’ 


2000 STOP 
END 


Cc KRKEKKREKKKKKKKEKKEKEKERKKEKKKKKKEKKKEREKKEKKEKRKKKEKRKEKKREREKKEKERKKKKKRKKRKKKEKKKEKK 


LPA11-K High-Level Language Program (Program B) 


This program (Example 4—2) is a more complex example of LPA11-K 
operations performed by the LPA11-K high-level language procedures. The 
following operations are demonstrated: 


¢ Program-requested loading of LPA11-K microcode 


¢ Setting the clock at a specified rate 


¢ Use of nondefault arguments whenever possible 


¢ An A/D sweep that uses an event flag 


¢ A D/A sweep that uses a completion routine 


¢ Buffer overrun set (buffer overrun is a nonfatal error) 


e Random channel list (RCL) addressing 


e Sequential channel addressing 


Table 4-9 lists the variables used in this program. 


Table 4~9 Program B Variables 


Variable 


AD 

DA 
IBUFAD 
IBUFDA 
RCL 
ADIOSB 


DAIOSB 


ISTAT 


Description 


An array of buffers for an A/D sweep (8 buffers of 500 words each) 
An array of buffers for a D/A sweep (2 buffers of 2000 words each) 
The IBUF array for an A/D sweep 

The IBUF array for a D/A sweep 

The array that contains the random channel list (RCL) 


The array that contains the I/O status block for the A/D sweep. 
Equivalenced to the beginning of IBUFAD 


The array that contains the I/O status block for the D/A sweep. 
Equivalenced to the beginning of IBUFDA 


Contains the status return from the high-level language calls 
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Example 4-2 LPA11-K High-Level Language Program (Program B) 





Cc 
C 
C 
Cc 
C 


qeoeaqandgaqaaqanan aanaaAN 


aqaagqgaNn 


aAaaqaqaannan 


KRREKEKKKKKKEKKKKKKKKKKKKKKKRKKEKKKEKKEK KKK KKK EKK KEKE KKK KKKKKKKKKKKKKKKKKKE 


Program B 
KKKKKKEKKKKKKEKKRKEKKKEKKREKKEKKEKKEKKKKRKEKEKKE KKK KKK KKEKKEKEKKEKEKK KK KKKKKKKKKKERE 


EXTERNAL FILLBF 
REAL*4 LPASXRATE 


INTEGER*2 AD (500,0:7),DA(2000,0:1),RCL(5) ,MODE, IPRSET 
INTEGER*2 ADIOSB (4) , DAIOSB (4) 


INTEGER*4 IBUFAD (50), IBUFDA(50) , LAMSKB (2) 
INTEGER*4 ISTAT, IERROR, IRATE, BUFNUM 


REAL*4 PERIOD 

COMMON /SWEEP/AD,DA, IBUFAD, IBUFDA 

EQUIVALENCE (IBUFAD(1),ADIOSB(1)), (IBUFDA(1),DAIOSB(1) ) 
PARAMETER MULTI=1, HBIT=’8000’X, LSTCHN=HBIT+7 


Set up random channel list. Note that the last word must have bit 
15 set. 


DATA RCL/2,6,3,4, LSTCHN/ 


KREKEKKEKKKKEKKKKKKEKREKKKK EK KKK KKK KEK KKK KKK KKK RK KKK KKK KKK EK KE KKK KKKKKKKKEK 


Load multirequest mode microcode and set the clock overflow rate 
to 5 kha. 


KKK KKE KK KKK KKK KEK KKK KKK KKK KEK KKK KKK KKK KKK KEKE KKK KKK KEK KKK KKK KKK KKKKEKER 


Load microcode on LPA11-K assigned to LPA11$3. 


CALL LPASLOADMC (MULTI, 3, ISTAT, IERROR) 
IF (.NOT. ISTAT) GO TO 5000 


Compute clock rate and preset. Set clock ’A’ on LPA11-K 
assigned to LPA11$3. 


PERIOD = LPASXRATE(.0002, IRATE, IPRSET, 0) 
IF (PERIOD .EQ. 0.0) GO TO 5500 


CALL LPASCLOCKA (IRATE, IPRSET, ISTAT, 3) 


IF (.NOT. ISTAT) GO TO 5000 
KKK RRR KK KKK KKK KKK KKK KKK KR RK KKK KKK KKK KKK KK RR RK KEK KKK KKK KK EK KR KR KKK 


Set up for A/D sweep 


KRRKEKKKKKKKKKKKKKKKKK KEK KKK KEKE KKK KKK KEK KKK KK KKK KK KK KKK KK KKK KKKKKEKEEEK 


Initialize IBUF array. Note the use of the LAMSKB argument because 
the LPA11-K assigned to LPA11$3 is used. 


CALL LPASSETIBF (IBUFAD, ISTAT, LAMSKB,AD(1,0),AD(1,1),AD(1,2), 
1 AD (1,3),AD(1,4),AD(1,5),AD(1,6),AD(1,7)) 
IF (.NOT. ISTAT) GO TO 5000 
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Example 4—2 (Cont.) LPA11-K High-Level Language Program (Program B) 





CALL LPASLAMSKS (LAMSKB, 3) 


Cc 
C Set up random channel list sampling (20 samples in a sample 
C sequence). 
C 
CALL LPASSETADC (IBUFAD, ,RCL, 20,0, ISTAT) 
IF (.NOT. ISTAT) GO TO 5000 
C 
C Release buffers for A/D sweep. Note that buffer 0 is not 
C released because buffer overrun will be specified as nonfatal. 
Cc 
CALL LPASRLSBUF (IBUFAD, ISTAT,1,2,3,4,5,6,7) 
IF (.NOT. ISTAT) GO TO 5000 
Cc KREKKKEKEKKKKKKKRKEKEKRKEKKRKKKKKKKKEKEKEKKKR KE KK KE KKK KKK KK KEE KKK KKKKKKEKKEKKKKSE 
c 
C Set up for D/A sweep 
Cc 
Cc KKEKEKKKKKKKKKKEKEKREKKKKKKKKKKEKKKKKK KEK KKK KKK KKK KKK KKK KK KKK KE KKKKEKKKKKKEKE 
Cc 
C Note that the same LAMSKB array can be used because the LAMSKB 
C contents apply to both A/D and D/A sweeps. 
Cc 
CALL LPASSETIBF (IBUFDA, ISTAT, LAMSKB, DA(1,0),DA(1,1) ) 
IF (.NOT. ISTAT) GO TO 5000 
Cc 
C Set up sampling parameters as follows: initial channel = 1. 
C Number of channels sampled each sample sequence = 2, channel 
C increment = 2, that is, sample channels 1 and 3 each sample 
C sequence. 
C 
CALL LPASSETADC (IBUFDA,,1,2,2,ISTAT) 
IF (.NOT. ISTAT) GO TO 5000 
Cc 
C Fill buffers with data for output to D/A. 
C 


(Application-dependent code is inserted here to fill buffers 
DA(1,0) through DA(2000,0) and DA(1,1) through DA(2000,1) with data). 
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Example 4—2 (Cont.) LPA11-K High-Level Language Program (Program B) 





Cc 

C Release buffers for D/A sweep. 

Cc 
CALL LPASRLSBUF (IBUFDA, ISTAT,0O,1) 
IF (.NOT. ISTAT) GO TO 5000 


KKKKKKKKKKKKKEKKEKKEKKKKKKKKKE KE KKK KK KKK KKK KKK KKK KKKKKKKKKKKEKKEKKKKKEKE 
Start both sweeps 


RKEKKKKKKKKKKEREKKRKKKKRKEKKKKKKEKKKEKKEKKKKRKEKKKE KKK KKKRKKRKKKKKEKKREKEKREKRKRKEKKAKKEE 


Start A/D sweep. Mode bits specify buffer overrun is nonfatal and 
multirequest mode. Sweep arguments specify 500 samples/buffer, 
Indefinite sampling, dwell = 10 clock overflows, synchronize using 
event flag 15, and a delay of 50 clock overflows. 


eananaangaanana 


MODE = 16384 + 64 
CALL LPASADSWP (IBUFAD, 500,0,MODE,10,%VAL(15) ,50,,,ISTAT) 
IF (.NOT. ISTAT) GO TO 5000 


Start D/A sweep. Mode specifies multirequest mode. Other 
arguments specify 2000 samples/buffer, fill 15 buffers, dwell = 25 
clock overflows, synchronize by calling the completion routine 
‘FILLBF’, and delay = 10 clock overflows. (See the FILLBF listing 
after the program B listing.) 


qaqagaagagaan 


MODE = 64 
CALL LPASDASWP (IBUFDA, 2000,15,MODE, 25,FILLBF,10,,,ISTAT) 
(.NOT. ISTAT) GO TO 5000 


RKKKKEKKKERKEKKEKKKKKRKERKKEKEKKKERKEKERKER ERK EKER KEKE KKRKKEKRKKRKEKEKKEKEKRKRKKKEKRKEEKE 


Wait for an A/D buffer and then process the data it contains. D/A 
buffers are filled asynchronously by the completion routine FILLBF. 


KRREKEKKKKEKKKEKEKKEKKEKKERKEKRKKEKERKERKEKKKEKRKEKR KER KKRKKRKKEKKEKRRERKEKRRREKERKKRKEKKEKKKE 


Wait for a buffer to be filled by A/D. If BUFNUM is less than 
zero, the sweep has stopped (either successfully or with an error). 


Paaagqaaqnaaana 


00 BUFNUM = LPASIWTBUF (IBUFAD) 
IF (BUFNUM .LT. 0) GO TO 1000 
C 
C There is A/D data in AD(1,BUFNUM) through AD (500,BUFNUM) 
C 


(Process the A/D data with the application-dependent code inserted 
here.) 
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Example 4—2 (Cont.) LPA11-K High-Level Language Program (Program B) 





Cc 
C Assume sweep should be stopped when the last sample in buffer . 
C equals 0. Note that the sweep actually stops when the buffer 
C currently being filled is full. Also note that LPASIWTBUF 
C continues to be called until there are no more buffers to process. 
C 
IF (AD(500,BUFNUM) .NE. 0) GO TO 200 
CALL LPASSTPSWP (IBUFAD,1,ISTAT) 
IF (.NOT. ISTAT) GO TO 5000 
Cc 
C After the data is processed, the buffer is released to be 
C filled again. Then the next buffer is obtained from A/D. 
C 
200 CALL LPASRLSBUF (IBUFAD, ISTAT, BUFNUM) 
IF (.NOT. ISTAT) GO TO 5000 
GO TO 100 
© 
C Enter here when A/D sweep has ended. Check for error or 
C successful end. (Note: Assume that the D/A sweep has already 
C ended - see completion routine FILLBF.) 
Cc 
1000 IF (ADIOSB(1)) GO TO 6000 


CALL LIBSSTOP (%VAL(ADIOSB (1) )) 


Cc 
C Enter here if there was an error returned from one of the 
C LPA11-K high-level language calls. ISTAT contains either 0 
C or a VMS status code. 
Cc 
5000 IF (ISTAT .NE. 0) CALL LIBSSTOP (%VAL(ISTAT) ) 
5500 PRINT *,’ERROR IN LPA11-K SUBROUTINE CALL’ 
GO TO 7000 


6000 PRINT *,’SUCCESSFUL COMPLETION’ 
7000 STOP 
END 
FOI OI I IIR IO III RII KOR KR KK 


Subroutine FILLBF 


RRREKRKEKEKKEKKEKRKEKRKKKKERKEKRKERKERKERKEKREKKRREKRKEKKRKKKEKRKKEKRKEKRKEKKEKRERRERKEKKKEKREKKRKKK 


The FILLBF subroutine is called whenever the D/A has emptied a 
buffer, and that buffer is available to be refilled. This 
subroutine gets the buffer, fills it, and releases it back to the 
LPA11-K. Note that the D/A sweep is stopped automatically after 

15 buffers have been filled. Also note that FILLBF is called by 

an AST handler. It is therefore called asynchronously from the 
main program at AST level. Care should be exercised when accessing 
variables that are common to both levels. 


AeaqaaqqnanaannanaanNnandndana 


INTEGER*2 AD(500,0:7),DA(2000,0:1),DAIOSB (4) 
INTEGER*4 IBUFAD (50) ,IBUFDA(50) , BUFNUM, ISTAT 
EQUIVALENCE (IBUFDA(1),DAIOSB(1)) 
COMMON /SWEEP/AD,DA, IBUFAD, IBUFDA 
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Cc 
C Get buffer number of next buffer to fill. 
Cc 


BUFNUM = LPASIGTBUF (IBUFDA) 
IF (BUFNUM .LT. 0) GO TO 3000 


C Fill buffer with data for output to D/A. 


(Application-dependent code is inserted here to fill buffer 
DA(1,BUFNUM) through DA(2000,BUFNUM) with data.) 


Cc 

C Release buffer 

C 
CALL LPASRLSBUF (IBUFDA, ISTAT, BUFNUM) 
GO TO 4000 

C 

C Check for successful end of sweep. 

Cc 

3000 IF (DAIOSB(1)) GO TO 4000 

Cc 

C Error in sweep 

Cc 


CALL LIBSSTOP (SVAL (DAIOSB (1) ) ) 


4000 RETURN 
END 
COR RRR III III I ICO kk 


LPA11-K QIO Functions Program (Program C) 


This sample program (Example 4-3) uses QIO functions to start an A/D 
data transfer from an LPA11-K. (The program assumes multirequest mode 
microcode has been loaded.) Sequential channel addressing is used. The 
data transfer is stopped after 100 buffers have been filled; no action is 
taken with the data as the buffers are filled. Note that this program starts 
the data transfer and then waits until the QIO operation completes. 
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Example 4-3 LPA11-K QIO Functions Program (Program C) 


KKEKKKKKKKKEKEK KKK KE KKK KKK KKK KKK KKK KKK KEKE KK EK KKK KK KKKKKKEKKKKKKKKKK KK 


Program C 


-TITLE LPA11-K EXAMPLE PROGRAM 


-IDENT /V01/ 
.PSECT LADATA, LONG 


IOSB: -BLKQ 1 
COUNT: .LONG 0 
CBUFF: 
-WORD “*X20A 
-WORD 3 
-LONG USW 
-LONG 4000 
-LONG DATA _BUFFERO 
-LONG 0 
-LONG 0 
-WORD 10 
-BYTE 0 
-BYTE 1 
-WORD 16 
-WORD 1 
-BYTE 0 
-BYTE 0 
-WORD 0 
-WORD 0 
-WORD 0 
USW: -WORD 0 
-ALIGN LONG 


DATA _BUFFERO: .BLKW 500 
DATA BUFFER1: .BLKW 500 
DATA_BUFFER2: .BLKW 500 
DATA BUFFER3: .BLKW 500 


Ne 


‘ee 


REKKKKKKKKKKKKKKKKKKKKKEKKKKKKKRKKKKKKKE KKK KKK KRKKKKRKKKKEKKKRKKKKKKKKKEKKK 


I/O status block 
Count of buffers filled 


Command buffer for start 
Data QIO 

Mode = Sequential channel 
Addressing, A/D, 
multirequest mode 

Valid buffer mask 

(4 buffers) 

User Status Word address 
Aggregate buffer length 
Address of data buffers 
No random channel list 
length 

No random channel list 
address 

Delay 

Start channel 

Channel increment 

Number of samples in 
sample sequence 

Dwell 

Start word number 

Event mark word 

Start word mask 

Event mark mask 

Fills out command buffer 


User Status Word 


Buffers must be 
longword aligned 
Data buffers 
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Example 4-3 (Cont.) LPA11-K QIO Functions Program (Program C) 





DEVNAME: .ASCID /LAAO/ 
CHANNEL: .BLKW 1 ; Contains channel number 
»-PSECT LACODE,NOWRT 


START: -ENTRY START, “m<> 
SASSIGN_S DEVNAM=DEVNAME, CHAN=CHANNEL ; Assign channel 
BLBS RO,5$ No error 
BRW ERROR Error 


Ne Ne 


5$: Set clock overflow rate 
To 2 khz. (1 mhz rate 

divided by 500 preset) 

SQIOW_S , CHAN=CHANNEL, FUNC=#I0$ SETCLOCK, - 


IOSB=IOSB,,,,P2=#1,P3=#*X143,P4#-500 


Ne Ne Ne 


BLBC RO, ERROR ; Error 
MOVZWL IOSB,RO 7 Pick up I/O status 
BLBC RO, ERROR ; Error 


Start data transfer 
Clear USW (start with 
buffer 0) 

Fill 100 buffers 


CLRW USW 


Ne Ne Ne Ne 


MOVL #100, COUNT 

$QIOW_S ,CHANNEL, #10$_STARTDATA, 
IOSB=I0SB, , ,P1=CBUFF, P2=#40, P3=#BFRAST 

BLBC RO, ERROR ; Error 


; Note that the QIO waits until it finishes. Normally, the data is 
; processed here as the buffers are filled. Check for error when 
7 the QIO completes. 


MOVZWL IOSB, RO 
BLBC RO, ERROR 
RET 


Pick up I/O status 
Error 
All done - exit 


we Ne Ne 


ERROR: Enter here if error 
status in RO 
Push onto stack 


Signal error 


PUSHL RO 
CALLS #1,G*LIBSSTOP 


“Ne Ne Ne Neo 


BFRAST: BFRAST,m*<> Buffer AST routine 
BFRAST is called whenever 


a buffer is filled 


Ne Ne Ne 


- WORD 0 
INCB USWt+1 3; Add 1 to buffer number 
CMP ZV #0,#3,USW+1, #3 ; Handle wraparound 
BLEQ 10$ 
CLRB USWt1 3; Use buffer 0 

10S: DECL COUNT ; Decrement buffer count 
BGTR 20$ 
BISB #*°X40, USW+1 + Enough buffers filled - 

; Set stop bit 

208: BICB #°X80,USW+1 ; Clear done bit 
RET 
- END START 


: KKKKKKEKKEKKEKKRKE KKK KEK KK KEK KEKE KER KKK KK KKK KKK K KEKE KKK ERK KERR KKERKKEKEKKKKEKE 





5 Line Printer Driver 


This chapter describes the use of the line printer drivers LPDRIVER and 
LCDRIVER. 





5.1 Supported Line Printer Devices 


The following sections describe the line printer controllers and line 
printers supported by the VMS operating system. 


5.1.1 LP11 Line Printer Controller 


The LP11 line printer controller provides an interface between the 
VAX UNIBUS adapter and the line printer. The LP11 performs the 
following functions: 


e Synchronizes single-character data transfers from the UNIBUS to the 
printer 


¢ Informs the VMS operating system about printer status 
e Enables the printer to gain control of the UNIBUS to report interrupts 


5.1.2 DMF32 and DMB32 Line Printer Controllers 


The DMF82 and DMB32 line printer controllers provide a direct memory 
access (DMA) interface between the VAX UNIBUS adapter (for the 
DMF82), or the VAXBI adapter (for the DMB32), and the line printer. 
The DMF32/DMB32 optionally perform the following functions: 


e Tab expansion 

e Carriage control 

e Line wrapping and truncation 
¢ Case conversion 

¢ Passall mode 


e Printall mode 


5.1.3. LP27 Line Printer 


The LP27 line printer is a high-speed, 132-column line printer, available 
with either a 64- or 96-character ASCII print set. The LP27-U is a fully 
buffered model that operates at a standard speed of up to 1200 lines per 
minute. Forms with up to six parts can be used for multiple copies. A 
version of the LP27 is available for operation of the printer up to 24.5 
meters (1000 feet) from the host. 
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LA11 DECprinter | 


The LA11 DECprinter I is a medium-speed printer that operates at a 
standard speed of 180 characters per second. It provides a forms length 
switch to set the top of form to any of 11 common lengths, a paper- 
out switch and alarm, and a variable forms width. The LA11 uses a 
96-character ASCII set; the column width is 132 characters. 


LNO1 Laser Page Printer 


The LNO1 laser page printer is a nonimpact printer that employs laser 
technology to produce high-quality print. Using electrophotographic 
imaging and xerographic printing, the LNO1 prints one page at a time 
at a rate of 12 pages per minute. The print resolution of 300 x 300 dots 
per square inch produces characters of even density and alignment. The 
LNO1 uses two, 188-character, fixed-space fonts; the column width is 132 
characters. 


LNOS3 Laser Page Printer 


The LNO3 laser page printer is a table-top, nonimpact page printer that 
uses laser imaging and xerographic printing techniques. The LN03 has a 
printing speed of 8 pages per minute with a print resolution of 300 x 300 
dots per square inch. Four built-in fonts are available. Several column 
widths, including 80 or 132 characters, are also available. 





Driver Features 


The line printer drivers provide output character formatting and error 
recovery. These features are described in the following sections. 


Output Character Formatting 
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In write virtual and write logical block operations, user-supplied 
characters are output as follows (write physical block data is not 
formatted, but output directly): 


¢ Rubouts are discarded. 


¢ Tabs move the horizontal print position to the next MODULO (8) 
position unless the LP$M_TAB characteristic is clear. 


e All lowercase alphabetic characters are converted to uppercase before 
printing (unless the characteristic specifying lowercase characters is 
set; see Section 5.4.3 and Table 5-2). 


e On printers where the line-feed, form-feed, vertical-tab, and carriage- 
return characters empty the printer buffer, returns are held back 
and output only if the next character is not a form feed, line feed, or 
vertical tab. Carriage returns are always output on units that have 
the LP$M_CR characteristic set (see Section 5.4.3 and Table 5-2). 


5.2.2 


5.3 


Error Recovery 
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e The horizontal print position is incremented on the output of all 
characters, including the space character. Characters are discarded if 
the horizontal print position is equal to or greater than the carriage 
width, unless the LP$M_WRAP characteristic is set or the 
LP$M_TRUNCATE characteristic is clear (see Section 5.3). 


¢ On printers without a mechanical form feed (the form-feed function 
characteristic is not set; see Section 5.4.3 and Table 5—2), a form feed 
is converted to multiple line feeds. The number of line feeds is based 
on the current line count and the page length. 


e Print lines are counted and returned to the caller in the second 
longword of the I/O status block. 


The VMS line printer drivers perform the following error recovery 
operations: 


e Ifthe printer is off line for 30 seconds, a “device not ready” message is 
sent to the system operator process. 


¢ Ifthe printer runs out of paper or has a fault condition, a “device 
not ready” message is sent to the system operator after 30 seconds. 
Successive messages, if they occur, are sent 1, 2, 4, 8, ... minutes 
after the initial message. 


¢ The current operation is retried every two seconds to test for a changed 
situation, such as the printer coming on line. 


¢ The current I/O operation can be canceled at the next timeout without 
the printer being on line. 


¢ When the printer comes on line, device operation resumes 
automatically. 


Line Printer Driver Device Information 


You can obtain information on printer characteristics by using the Get 
Device/Volume Information ($GETDVI) system service. (See the VMS 
System Services Reference Manual.) 


$GETDVI returns line printer characteristics when you specify the item 
codes DVI$_DEVCHAR and DVI$_DEVDEPEND. Tables 5-1 and 5-2 

list these characteristics. The $DEVDEF macro defines the device- 
independent characteristics; the $LPDEF macro defines the device- 
dependent characteristics. DVI$_DEVDEPEND returns a longword field 
that contains the device-dependent characteristics in the three low-order 
bytes and the page length in the high-order byte. Maximum page length is 
255. 


DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class 
names, which are defined by the $DCDEF macro. The device type is a 
value that corresponds to the printer, for example, LP$_LP27 or LP$_ 
LA11. The device class for printers is DC$_LP. DVI$_DEVBUFSIZ returns 
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the page width, which is a value in the range of 0 through 255 on a DMF32 
controller and 0 through 65535 on an LP11 or a DMB32 controller. 


Table 5-1 Printer Device-independent Characteristics 


Characteristic’ 


DEV$M_SPL 
DEV$M_AVL 


DEV$M_REC 
DEV$M_CCL 
DEV$M_ODV 


Meaning 
Dynamic Bits (Conditionally Set) 


Device is spooled. 
Printer is on line and available. 


Static Bits (Always Set) 


Device is record-oriented. 
Carriage control is enabled. 
Device is capable of output. 


'Defined by the $DEVDEF macro. 


Table 5-2 Device-Dependent Characteristics for Line Printers 


Value’ 


LP$M_CR 
LP$M_FALLBACK 


LP$M_LOWER 


LP$M_MECHFORM 


LP$M_PASSALL 


LP$M_PRINTALL 


LP$M_TAB 
LP$M_TRUNCATE 


Meaning 


Printer requires carriage return. (See Section 5.2.1). 


Printer translates multinational characters to a seven- 

bit equivalent representation if possible. Otherwise, an 
underscore character (_) replaces the character. LPM$M_ 
FALLBACK has no effect on physical block operations. See 
Appendix B for a list of multinational characters. 


Printer can print lowercase characters. If this value is not set, 
all lowercase characters are converted to uppercase when 
output. (LP$M_LOWER has no effect on write physical block 
operations.) 


Printer has mechanical form feed. This characteristic is 
used when variable form length is required, such as in 
check printing. Driver sends ASCII form feed (decimal 12). 
Otherwise, multiple line feeds are generated. The page 
length determines the number of line feeds. 


All output data is in binary (no data interpretation occurs). 
Data termination occurs when the buffer is full (default buffer 
size is 132 bytes). Character formatting is disabled. 


All printing and nonprinting characters are transferred to the 
printer, while character formatting remains enabled. 


Printer enables tab expansion. 


Printer truncates records that are larger than the carriage 
width. 


'Defined by the $LPDEF macro. 
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Table 5-2 (Cont.) Device-Dependent Characteristics for Line Printers 
Value" Meaning 
LP$M_WRAP Printer wraps records that are larger than the carriage width. 


If a string of text is longer than the width specified in the 
second longword, the string is continued on the next line. 


'Defined by the $LPDEF macro. 


Line Printer Function Codes 


Write 


The basic line printer I/O functions are write, sense mode, and set mode. 
None of the function codes take function modifiers. 


The line printer write functions print the contents of the user buffer on 
the designated printer. 


The write functions and their QIO function codes are: 

¢ JO$ WRITEVBLK—Write virtual block 

e I0$_WRITELBLK—Write logical block 

¢ I0O$ WRITEPBLK—Write physical block (the data is not formatted, 
but output directly, as in PASSALL mode on terminals) 

The write function codes can take the following device- or function- 

dependent arguments: 

¢ Pi—The starting virtual address of the buffer that is to be written 

e P2—The number of bytes that are to be written 


e P4—Carriage control specifier except for write physical block 
operations (Write function carriage control is described in 
Section 5.4.1.1.) 


P3, P5, and P6 are not meaningful for line printer write operations. 


In write virtual block and write logical block operations, the buffer 
specified by Pl and P2 is formatted for the selected line printer and 
includes the carriage control information specified by P4. The default 
buffer size is 132 bytes. 


If the printer is not set spooled, write virtual block and write logical block 
operations perform the same function. If the printer is set spooled, a write 
logical block function queues the I/O to the printer, and a write virtual 
block function queues the I/O to the intermediate device, usually a disk. 


All lowercase characters are converted to uppercase if the characteristics 
of the selected printer do not include LP$M_LOWER. (This does not apply 
to write physical block operations.) 
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Multiple line feeds are generated for form feeds only if the printer does 
not have a mechanical form feed (LP$M_MECHFORM) characteristic. The 
number of line feeds generated depends on the current page position and 
the page length. 


Section 5.2.1 describes character formatting in greater detail. 


Write Function Carriage Control 


The P4 argument is a longword that specifies carriage control. Carriage 
control determines the next printing position on the line printer. (P4 is 
ignored in a write physical block operation.) Figure 5-1 shows the P4 
longword format. 


Figure 5-1 P4 Carriage Control Specifier 


3 2 1 0 
P4: | POSTFIX | PREFIX | (Not Used) | FORTRAN 
ZK-0664-GE 


Only bytes 0, 2, and 3 in the longword are used. Byte 1 is ignored. If 
the low-order byte (byte 0) is not 0, the contents of the longword are 
interpreted as a FORTRAN carriage control specifier. Table 5-3 lists the 
possible byte 0 values (in hexadecimal) and their meanings. 


If the low-order byte (byte 0) is 0, bytes 2 and 3 of the P4 longword 

are interpreted as the prefix and postfix carriage control specifiers. The 
prefix (byte 2) specifies the carriage control before the buffer contents are 
printed. The postfix (byte 3) specifies the carriage control after the buffer 
contents are printed. The sequence is as follows: 


1 Prefix carriage control 

2 Print 

3 Postfix carriage control 

The prefix and postfix bytes, although interpreted separately, use the same 


encoding scheme. Table 5~4 shows this encoding scheme in hexadecimal 
format. 
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Table 5-3 Write Function Carriage Control (FORTRAN: byte 0 not equal 


Meaning 


Single-space carriage control (Sequence: 


carriage-return/line-feed combination’, print 
buffer contents, return) 


Double-space carriage control (Sequence: 


carriage-return/line-feed combination, carriage- 
return/line-feed combination, print buffer 
contents, return) 


Page eject carriage control (Sequence: form 


feed, print buffer contents, return) 


Overprint carriage control; allows double printing 


for emphasis or for special effects (Sequence: 
print buffer contents, return) 


Prompt carriage control (Sequence: carriage- 


return/line-feed combination, print buffer 
contents) 


to 0) 
Byte 0 Value ASCII 
(hexadecimal) Character 
20 (space) 
30 0 
31 1 
2B + 
24 $ 
All other 
values 


Same as ASCIl space character: single-space 
carriage control 


1A carriage-return/line-feed combination is a carriage return followed by a line feed. 


Table 5-4 Write Function Carriage Control (P4 byte 0 equal to 0) 


Prefix/Postfix Bytes (Hexadecimal) 


Bits 
Bit 7 0-6 
0 0 
0 1—7F 


Bit7 Bit6é  BitS  Bits0—4 
1 0 0 1-1F 
1 1 0 1-1F 


Meaning 


No carriage control is specified, that is, 
NULL. 


Bits 0 through 6 are a count of carriage- 
return/line-feed combinations. 


Meaning 


Output the single ASCII control character 
specified by the configuration of bits 0 
through 4 (seven-bit character set). 


Output the single ASCII control character 
specified by the configuration of bits 0 
through 4, which are translated as ASCII 
characters 128 through 159 (eight-bit 
character set; see Appendix B). 


Figure 5-2 shows the prefix and postfix hexadecimal coding that produces 
the carriage control functions listed in Table 5-3. Prefix and postfix coding 
provides an alternative way to achieve these controls. 
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In the first example, the prefix/postfix hexadecimal coding for a single- 
space carriage control (carriage-return/line-feed combination, print buffer 
contents, carriage-return) is obtained by placing the value (1) in the 
second (prefix) byte and the sum of the bit 7 value (80) and the return 
value (D) in the third (postfix) byte: 


80 (bit 7 = 
+ D (return) 


8D (postfix = return) 
Figure 5—2 Write Function Carriage Control (Prefix and Postfix Coding) 


bh 


) 


(Space) Sequence: 
Prefix = NL 
ocd ee 
Postfix = CR 
nO" Sequence: 
Prefix = NL, NL 
Postfix = CR 
nym Sequence: 
Prefix = FF 
pa} ap | eT | Pri 
Postfix = CR 
nn Sequence: 
Prefix = NULL 
Postfix = CR 
"gu Sequence: 
Prefix = NL 
pa} oo Ft TT d i 
Postfix = NULL 
Example: Skip 24 lines before printing. Sequence: 
Prefix = 24NL 
pa] ap | ts | | ri 
Postfix = CR 
ZK-0665-GE 
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Sense Printer Mode 


Set Mode 


The sense printer mode function senses the current device-dependent 
printer characteristics and returns them in the second longword of the I/O 
status block. No device- or function-dependent arguments are used with 
10$_SENSEMODE. 


Set mode operations affect the operation and characteristics of the 
associated line printer. The VMS operating system provides two types 

of set mode functions: set mode and set characteristics. Set mode requires 
logical I/O privilege. Set characteristics requires physical I/O privilege. 
The following function codes are provided: 


¢ I0$ SETMODE 
e I0$_SETCHAR 


These functions take the following device- or function-dependent argument 
(other arguments are not valid): 


P1—tThe address of a characteristics buffer 


Figure 5-3 shows the quadword P1 characteristics buffer for IO$_ 
SETMODE. Figure 5—4 shows the same buffer for IO$_SETCHAR. 


Figure 5-3 Set Mode Buffer 


31 24 23 16 15 0 


Page Length Printer Characteristics 


ZK-0666-GE 











In the buffer, the device class is DC$_LP. The printer type is a value that 
corresponds to the printer: DT$_LP27 or DT$_LA11. The type can be 
changed by the IO$_SETCHAR function. The page width is a value in the 
range of 0 through 255 on a DMF32 controller and 0 through 65535 on an 
LP11 or DMB382 controller. 


The printer characteristics part of the buffer can contain any of the values 
listed in Table 5-2. 
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l/O Status Block 
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Figure 5-4 Set Characteristics Buffer 


31 24 23 16 15 


8 7 0 
Page Length Printer Characteristics 


ZK-0667-GE 









Application programs that change specific line printer characteristics 
should perform the following steps: 


1 Use the I0$¢_SENSEMODE function to read the current 
characteristics. 


2 Modify the characteristics. 


3 Use the set mode function to write back the results. 


Failure to follow this sequence will result in clearing any previously set 
characteristic. 


The I/O status blocks (IOSB) for the write and set mode I/O functions 
are shown in Figures 5—5 and 5-6. Appendix A lists the status returns 
for these functions. (The VMS System Messages and Recovery Procedures 
Reference Manual provides explanations and suggested user actions for 
these returns.) 
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Figure 5-5 IOSB Contents — Write Function 


31 16 15 0 


Number of Lines the Paper Moved* 


* 0 if lO$_WRITEPBLK 






ZK-0668—GE 


Figure 5-6 IOSB Contents — Set Mode Function 


31 16 15 


oO 


ZK-0669-GE 





5.6 Line Printer Driver Programming Example 


The following sample program (Example 5-1) is an example of I/O to the 
line printer that shows how to use the different carriage control formats. 
This program prints out the contents of the output buffer (OUT_BUFFER) 
10 times using 10 different carriage control formats. The formats are held 
in location OUTPUT_FORMAT. 
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Example 5-1 Line Printer Program Example 
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-TITLE LINE PRINTER PROGRAMMING EXAMPLE 
-IDENT /01/ 


; Define necessary symbols. 


SIODEF ;Define I/O function codes 


; Allocate storage for the necessary data structures. 


; Allocate output buffer and fill with required output text. 


OUT_BUFFER: 
-ASCII "VAX _PRINTER_EXAMPLE" 


OUT_BUFFER_SIZE=.-OUT_BUFFER ;Define size of output string 
; Allocate device name string and descriptor. 


: 
, 


DEVICE_DESCR: ; 

. LONG 20$—10S ;Length of name string 

. LONG 10$ ;Address of name string 
108: -ASCII /LINE_PRINTER/ ;Name string of output device 
20$: ;Reference label to calculate 
; ;length 


; Allocate space to store assigned channel number. 
DEVICE CHANNEL: ; 

. BLKW 1 7;Channel number 
; Now set up the carriage control formats. 


° 
, 


OUTPUT FORMAT: ; 
. BYTE 0,0,0,0 ;No carriage control 
-BYTE 32,0,0,0 ;Blank=LFt+...TEXT...+CR 
- BYTE 48,0,0,0 7 Zero=LF+LF+...TEXT...+CR 
. BYTE 49,0,0,0 7One=FFt+...TEXT...+CR 
. BYTE 43,0,0,0 ;Plus=Overprint...+CR 
-BYTE 36,0,0,0 ;Dollar=LF+TEXT (Prompt) 


+ Now set up the prefix-postfix carriage control formats. 


° 
, 


- BYTE 0,0,1,141 ;LF+...TEXT...+CR 

- BYTE 0,0,24,141 ;24LF+...TEXT...+CR 
. BYTE 0,0,2,141 ;LE+LF+...TEXT...+CR 
- BYTE 0,0,140,141 ;PF+...TEXT...+CR 





(continued on next page) 
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5.6 Line Printer Driver Programming Example 


Example 5—1 (Cont.) Line Printer Program Example 





’ 


Start Program 


KKEKEKKEKKKKEKKEKRKKEKKRKKKKKEK KE KKK KKK KKK KKKKEKKKRKKKKKEKKKKKKKKEKEKKKKKKKKKKKK 


KKKEKEKKKKEKKKKKKKKKKKKKKEKKKKKEKK KK KK KKK KKKKK EK KKK KKKEKKEKKEKKKKKEKKKKKKKKKE 


+ The program assigns a channel to the output device, sets up a loop 
; count for the number of times it wishes to print, and performs ten 


; QIO and wait 


; deassigned. 


; First, 


; Start 


30S: 


40S: 
50S: 


(SQIOW) system service requests. The channel is then 


-ENTRY PRINTER_EXAMPLE, “M<R2,R3> ;Program starting address 


assign a channel to the output 


SASSIGN_S DEVNAM=DEVICE_DESCR, - 


CHAN=DEVICE CHANNEL 
BLBC RO,508 
MOVL #11,R3 
MOVAL OUTPUT FORMAT, R2 


the printing loop. 


$QIOW_S CHAN=DEVICE_CHANNEL, - 
FUNC=#1I0$ WRITEVBLK, - 
P1=OUT_BUFFER, - 
P2=#OUT_BUFFER_SIZE,- 
P4=(R2)+ 


BLBC RO, 40$ 

SOBGTR R3,30$ 

$DASSGN_S CHAN=DEVICE_CHANNEL 
RET 


- END PRINTER_EXAMPLE 


device. 


;Assign a channel to printer 


;If low bit = 0, assign failure 
;Set up loop count 

;Set up o/p format address 

ean RZ 


7;Print on device channel 

3;I/O function is write virtual 
;Address of output buffer 
;Size of buffer to print 
;Format control in R2 

;will autoincrement 

;If low bit = 0, I/O failure 
;Branch if not finished 
;Deassign channel 

;Return 
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This chapter describes the use of the VMS magnetic tape drivers, drives, 
and controllers. These drivers support the devices listed in Table 6-1. 
Table 6-1 Supported Magnetic Tape Devices 


Recording Density (bpi) Tape Max. Data Transfer 





No. of —____ = )0 EO Speed_=—s Rate Recording 
Drive' Code Tracks 800 1600 6250 (ips) (bps) Method? 
HSC-Series Controllers 
TA78 MU 9 No Yes Yes 125 200,000 (1600 bpi) PE or GCR 
781,250 (6250 bpi) 
TA792 ss MU 9 No Yes Yes 125 769,000 PE or GCR 
TAS1 MU 9 No Yes Yes 250r 120,000 (1600 bpi) PE or GCR 
75 468,750 (6250 bpi) 
TA9Q0® MU 18 No No 38,000 79 2,100,000° X3B5 
LESI Adapters 
RV20 MU 9 No No Yes N/A 1.33 MB Write-once 
optical disk 
TQ81 MU 9 No Yes Yes 25 or 120,000 (1600 bpi) PE or GCR 
75 468,750 (6250 bpi) 
Tussi? = =MU 9 No Yes Yes 25 or 120,000 (1600 bpi) PE or GCR 
75 468,750 (6250 bpi) 
TU81- MU 9 No Yes Yes 25 or 120,000 (1600 bpi) PE or GCR 
Plus 75 468,750 (6250 bpi) 
TMO3 Controller 
TE16 MT 9 Yes Yes No 45 36,000 (800 bpi) NRZI or PE 
72,000 (1600 bpi) 
TU45 MT 9 Yes Yes No 75 60,000 (800 bpi) NRZI or PE 


420,000 (1600 bpi) 


'The RV20, TK70, TQK50, TUK50, TU81, TU81-Plus, TA78, TU78, TA81, and TA9O are tape mass storage control protocol 
(TMSCP) drives. 


2NRZI = non-return-to-zero-inverted; PE = phase encoded; GCR = group-coded recording; MFM = modified frequency 
modulation; HDMFM = high density modified frequency modulation; X3B5 = format adheres to the proposed ANSI standard 
X3B5. 


3Has a self-contained controller. 
®Dependent upon host system capabilities. Has a data collection and transfer rates of 2.1 MB per second. 


(continued on next page) 
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Table 6—1 (Cont.) Supported Magnetic Tape Devices 


Tape Max. Data Transfer 
No. of Speed Rate Recording 


Drive’ Code Tracks 800 1600 6250 (ips) (bps) Method? 


Recording Density (bpi) 


TMO3 Controller 
TU77 MT 9 Yes Yes No 125 100,000 (800 bpi) NRZI or PE 


200,000 (1600 bpi) 
TM78 Controller 


TU78 MF 9 No Yes Yes 125 200,000 (1600 bpi) PE or GCR 
781,250 (6250 bpi) 





T™M79 Controller 


TU79 MF 9 No Yes Yes 125 769,000 PE or GCR 


TBK70 and TQK70 Controllers 





TK70 MU 48 No No 10000 100 90,000 HDMFM 





TUK50, TQK50, and TZK50 Controllers 





TK50° MU 224 No No 6666 75 45,000 MFM 
TZ30* MU 224 No No 6666 75 45,000 MFM 


TS11 Controller 


TS04 MS 9 No Yes No 45 72,000 PE 

TS05 MS 9 No Yes No 25 40,000 PE 

Tuso® MS 9 No Yes No 25 or 160,000 PE 
100 


'The RV20, TK70, TQK50, TUK50, TU81, TU81-Plus, TA78, TU78, TA81, and TA90 are tape mass storage contro! protocol 
(TMSCP) drives. 


2NRZI = non-return-to-zero-inverted; PE = phase encoded; GCR = group-coded recording; MFM = modified frequency 
modulation; HDMFM = high density modified frequency modulation; X3B5 = format adheres to the proposed ANSI standard 
X3B5. 


3Has a self-contained controller. 
4Each track written separately—not in parallel. 


5The TK50 is a tape mass storage control protocol (TMSCP) device when configured on ( ... BA23 BA123 w/s) systems. The 
TK50 has a self-contained controller when configured on VAXstation 2000 and MicroVAX 2000 systems. 
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Supported Magnetic Tape Controllers 


The following sections describe the VMS magnetic tape controllers. 


TMO03 Magnetic Tape Controller 


The TM03 magnetic tape controller supports up to eight TE16, TU45, or 
TU77 tape drives. These dual-density (800 or 1600 bpi) drives differ in 
speed: the TE16, TU45, and TU77 read and write data at 45, 75, and 125 
inches per second, respectively. Each drive can hold one 2400-foot, 9-track 
reel with a capacity of approximately 40 million characters. The TM03 
controller is connected to the MASSBUS through a MASSBUS adapter. 


TS11 Magnetic Tape Controller 


The TS11 magnetic tape controller connects to the UNIBUS through a 
UNIBUS adapter and supports one TS04 tape drive. The TS11/TS04 
is a single-density tape system that supports 1600-bpi, phase-encoded 
recording. 


The TSU05 and the TSV05 magnetic tape drives are used with UNIBUS 
and Q-bus systems, respectively. 


TM78 and TM79 Magnetic Tape Controllers 


The TM78 and TM79 magnetic tape controllers support up to four TU78 
tape drives. These high-performance, dual-density drives (1600 or 6250 
bpi) operate at 125 inches per second (ips) using a 2400-foot reel of tape 
with a capacity of approximately 146 million characters when recorded in 
the GCR (6250 bpi) mode. The TM78 and TM79 controllers are connected 
to the MASSBUS through a MASSBUS adapter. 


TU80 Magnetic Tape Subsystem 


The TU80 is a single-density, dual-speed (25 or 100 ips) magnetic tape 
subsystem that uses streaming tape technology (see Section 6.2.7). It 
supports one drive per subsystem. The TU80 connects to the UNIBUS 
through a UNIBUS adapter and completely emulates the TS11 magnetic 
tape controller. 


TU81 and TA81 Magnetic Tape Subsystems 


The TU81 and the TA81 are high-performance, dual-density (1600 or 
6250 bpi), dual-speed (25 or 75 ips) magnetic tape subsystems that use 
streaming tape technology (see Section 6.2.7). The TU81 connects to the 
UNIBUS through a UNIBUS adapter. The TA81 attaches to an HSC50 
controller. Both drives are managed with the tape mass storage control 
protocol (TMSCP). 
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6.1.6 TU81-Plus Magnetic Tape Subsystem 


The TU81-PLUS is an enhanced version of the TU81 streaming tape 
subsystem. It is a 9-track, dual-speed, dual-density, ANSI-standard, half- 
inch magnetic tape subsystem. In addition, it has a 256-kilobyte (KB) 
cache buffer that temporarily stores commands and data moving to and 
from the tape unit. The buffer increases the amount of time the tape 
drive is able to stream, thereby increasing performance. The TU81-PLUS 
connects to all VAXBI, UNIBUS, and Q-bus systems using the KLESI-B, 
KLESI-U, and KLESI-Q adapters. 


6.1.7 TA90 Magnetic Tape Subsystem 


The TA90 is a 5- by 4-inch, 200-MB cartridge tape, fully read- and write- 
compatible with the IBM® 3480 format. The TA90 includes a master 
controller and a dual transport unit. As many as three additional dual 
transport slave units can be connected to a single TA90 master controller 
for a total of eight drives. The controller connects to the HSC 5X-DA 
high-speed channel card in the HSC. 


TA90 tape drives can be equipped with optional stack loaders for 
unattended backup operations. Each TA90 master has two dual-port 
STI connections to the HSC. Such dual pathing allows each control 
unit to service two HSC controllers which significantly increases tape 
drive availability. The TA90 subsystem includes a 2-MB cache which 
allows the controller to prefetch upcoming commands and store them 
while completing current data transfers. This behavior helps optimize 
performance. The TA90 is a TMSCP device. 


6.1.8 RV20 Write-Once Optical Drive 


The RV20, a 2-gigabyte, double-sided, write-once optical (WORM) disk 
drive is accessed sequentially similar to a tape. A 100-bit error correction 
code (ECC) protects user data. The controller performs bad block 
replacement. Three RV20 slaves can be daisy-chained to the subsystem 
controller in the RV20 master for a total of four drives. 


RV02 cartridges can be used on any DIGITAL RV20 optical subsystem. 


The average access time is 212.5 ms with an average seek rate of 150 ms. 
The maximum data transfer rate is 262 KB per second (formatted and 
sustained) with a burst rate of 1.33 MB per second. 


6.1.9 TK50 Cartridge Tape System 


The TK50 is a 95-MB, 5.25-inch cartridge tape system that uses streaming 
tape technology (see Section 6.2.7). The TK50 records data serially on 

22 tracks using serpentine recording, rather than on separate (parallel) 
tracks. Data written to tape is automatically read as it is written. A CRC 
check is performed and the controller is notified immediately if an error 
occurs on the tape. 
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The TQK50 is a dual-height Q-bus controller for the TK50 tape drive. The 
TUK50 is a UNIBUS controller for the same drive. The TZK50 is a SCSI 
controller for the TK50 tape. Both the TQK50 and the TUK50 are TMSCP 
devices. 


Section 6.1.12 describes compatibility among the TK50, TK70, and TZ30 
magnetic tape cartridge systems. 


6.1.10 TK70 Cartridge Tape System 


The TK70 is a 295-MB, 5.25-inch, streaming cartridge tape system. (See 
Section 6.2.7 for information about streaming tape technology.) The 
TK70 tape drive records data serially on 48 tracks using serpentine 
recording, rather than separate (parallel) tracks. Data written to the tape 
is automatically read as it is written. A CRC check is performed and the 
controller is notified immediately if an error occurs on the tape. 


The TQK70 is a dual-height, Q-bus controller for the TK70 magnetic 
tape drive. The TK70 subsystem includes a 38-KB cache to optimize 
performance. The TBK70 is a VAXBI-bus controller for the same drive. 
Section 6.1.12 describes compatibility between the TK50 and TK70 
magnetic tape cartridge systems. 


6.1.11 1230 Cartridge Tape System 


The TZ30 is a 95-MB, 5.25-inch, half-height cartridge streaming tape drive 
with an embedded SCSI controller. See Section 6.2.7 for information 
about streaming tape technology. The TZ30 uses TK50 cartridge 

tapes. It records data serially on 22 tracks using serpentine recording. 
Section 6.1.12 describes compatibility between the TK50, TK70, and TZ30 
magnetic tape cartridge systems. 


6.1.12 Read and Write Compatibility Among Cartridge Tape Systems 


When you insert a cartridge tape into the TZ30, TK50, and TK70 tape 
drives, the hardware initializes the media to a device-specific recording 
density automatically. 


Depending on the type of cartridge and the type of drive on which it is 
formatted (inserted and initialized), full read and write access to tape 
cartridges may not be permitted. 


Formatting a Blank TK50 Cartridge Tape 


A blank, unformatted TK50 cartridge can be formatted on the TK50, 
TK70, and TZ30 cartridge systems. For example, a TK70 tape drive has 
full read and write access to a TK50 cartridge formatted on a TK70 drive. 
Once the cartridge tape is formatted on a particular tape drive, the tape 
drive has full read and write access to the cartridge tape. 
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Formatting a Previously Initialized TK50 Cartridge Tape 


If a TK50 cartridge tape is formatted on a TZ30 or TK50 cartridge tape 
drive, the TZ30 and TK50 drives initialize the TK50 cartridge to TK50 
density. The following table summarizes the types of access available: 


TK50 
Controller Read Write 
TZ30' Yes Yes 
TQK50 Yes Yes 
TQK70 Yes No 


1Has an internal controller. 


The TK70 tape drive can read data on a TK50 cartridge formatted on a 
TK50 or TZ30 tape drive. 


Formatting a TK50 Cartridge Tape on a TK70 Tape Drive 


If a TK50 or TK52 cartridge tape is formatted on a TK70 tape drive, the 
TK70 cartridge tape drive initializes the TK50 or TK52 cartridge tape 
to TK70 density. The following table summarizes the types of access 
available: 


TK50 TK52 
Controller Read Write Read Write 
TZ30' No No No No 
TQK50 No No No No 
TQK70 Yes Yes Yes Yes 


1Has an internal controller. 


The TK50 and TZ30 tape drives cannot read or write data on a TK50 
cartridge tape formatted on a TK70 drive. 





The VMS magnetic tape drivers provide the following features: 
¢ Multiple master adapters and slave formatters 


¢ Different types of devices on a single MASSBUS adapter; for example, 
an RP05 disk and a TM03 tape formatter 


e Reverse read function (except for the TZ30 and TK50 on TUK50 and 
TQK50 controllers) 


e Reverse data check function (except for TZ30, TS11, and TK50 on 
TUK50 and TQK50 controllers) 


¢ Data checks on a per-request, per-file, or per-volume basis (except for 
TS11) 


Magnetic Tape Drivers 
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e Full recovery from power failure for online drives with volumes 
mounted, including repositioning by the driver (except on VAXstation 
2000 and MicroVAX 2000 systems) 


e Extensive error recovery algorithms; for example, non-return-to-zero- 
inverted (NRZI) error correction 


¢ Logging of device errors in a file that may be displayed by field service 
or customer personnel 


e Online diagnostic support for drive level diagnostics 


The following sections describe master and slave controllers, and data 
check and error recovery capabilities in greater detail. 


6.2.1 Dual Path Tape Drives 


A dual-path HSC tape drive is a drive that connects to two HSCs, both 
of which have the same nonzero tape allocation class. The VMS operating 
system recognizes the dual-pathed capability of such a tape drive under 
the following circumstances: (1) the VMS operating system has access to 
both HSCs and (2) select buttons for both ports are depressed on the tape 
drive. 


If one port fails, the VMS operating system switches access to the 
operational port automatically, provided that the allocation class 
information has been defined correctly. 


6.2.2. Dynamic Failover and Mount Verification 


Dynamic failover occurs on dual-pathed tape drives if mount verification is 
unable to recover on the current path and an alternate path is available. 
The failover occurs automatically and a aad and then mount 
verification proceeds. 


A device enters mount verification when I/O request fails because 
the device has become inoperative. This might occur in the following 
instances: 


e The device is place offline accidentally. 
¢ The active port of an HSC-connected drive fails. 
e A hardware error occurs. 


e The device is set to write protected during a write operation. 
When the device comes back online, either through automatic failover or 
operator intervention, the VMS operating system validates the volume, 


restores the tape to the position when the I/O failure occurred, and retries 
the failed request. 
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Tape Caching 


The RV20, TA90, TK70, and TU81-Plus contain write-back volatile 
caches. The host enables write-back volatile caches explicitly, either on 
a per-unit basis or on a per-command basis. To enable caching on a per- 
unit basis, the user can enter the DCL MOUNT command specifying the 
qualifier /CACHE=TAPE_DATA. 


The VMS Backup Utility enables caching on a per-command basis. The 
user can implement caching on a per-command basis at the QIO level 

by using the IO$M_NOWAIT function modifiers on commands where it 

is legal. (See Table 6-5.) In the unlikely event that cached data is lost, 
the system returns a fatal error and the device accepts no further I/O 
requests. The IO$M_FLUSH function code can be used to ensure that all 
write-back-cached data has been written out to the specified tape unit. The 
10$_PACKACK, I0$_UNLOAD, I0$_REWINDOFF, and I0$_AVAILABLE 
function codes also flush the cache. 


Master Adapters and Slave Formatters 


Data Check 


The VMS operating system supports the use of many master adapters 
of the same type on a system. For example, more than one MASSBUS 
adapter (MBA) can be used on the same system. A master adapter is a 
device controller capable of performing and synchronizing data transfers 
between memory and one or more slave formatters. 


The VMS operating system also supports the use of multiple slave 
formatters per master adapter on a system. For example, more than 
one TM03 or TM78 magnetic tape formatter per MBA can be used on a 
system. A slave formatter accepts data and commands from a master 
adapter and directs the operation of one or more slave drives. The TM03 
and the TM78 are slave formatters. The TE16, TU45, TU77, and TU78 
magnetic tape drives are slave drives. 


After successful completion of an I/O operation, a data check is made to 
compare the data in memory with that on the tape. After a write or read 
(forward) operation, the tape drive spaces backward, and then performs a 
write check data operation. After a read operation in the reverse direction, 
the tape drive spaces forward, and then performs a write check data 
reverse operation. With the exception of TS04 and TU80 drives, magnetic 
tape drivers support data checks at the following three levels: 


e Per request—You can specify the data check function modifier 
(IO$M_DATACHECK) on a read logical block, write logical block, read 
virtual block, write virtual block, read physical block, or write physical 
block J/O function. 


e Per volume—yYou can specify the characteristics “data check all reads” 
and “data check all writes” when the volume is mounted. The VMS 
DCL Dictionary describes volume mounting and dismounting. The 


6.2.6 


Note: 


Error Recovery 
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VMS System Services Reference Manual describes the Mount Volume 
($MOUNT) and Dismount Volume ($DISMOU) system services. 


e Per file—You can specify the file attributes “data check on read” 
or “data check on write.” File access attributes are specified when 
the file is accessed. Chapter 1 of this manual and the VMS Record 
Management Services Manual both describe file access. 


Data check is distinguished from a BACKUP/VERIFY operation, which 
writes an entire save set, rewinds, and then compares the tape to the 
original tape. 


See Section 6.1.9 for information on TK50 data check. 


Read and write operations with data check can result in very slow 
performance on streaming tape drives. 


Error recovery in the VMS operating system is aimed at performing all 
possible operations that enable an I/O operation to complete successfully. 
Magnetic tape error recovery operations fall into the following two 
categories: 


e Handling special conditions, such as power failure and interrupt 
timeout 


e Retrying nonfatal controller or drive errors 


The error recovery algorithm uses a combination of these types of error 
recovery operations to complete an I/O operation. 


Power failure recovery consists of repositioning the reel to the position 
held at the start of the I/O operation in progress at the time of the power 
failure, and then reexecuting this operation. This repositioning might 

or might not require operator intervention to reload the drives. When 
such operator intervention is required, “device not ready” messages are 
sent to the operator console to solicit reloading of mounted drives. Power 
failure recovery is not supported on VAXstation 2000 and MicroVAX 2000 
systems. 


Device timeout is treated as a fatal error, with a loss of tape position. A 
tape on which a timeout has occurred must be dismounted and rewound 
before the drive position can be established. 


If a nonfatal controller/drive error occurs, the driver (or the controller, 
depending on the type of drive) attempts to reexecute the I/O operation up 
to 16 times before returning a fatal error. The driver repositions the tape 
before each retry. 


The inhibit retry function modifier (IO$M_INHRETRY) inhibits all normal 
(nonspecial conditions) error recovery. If an error occurs, and the request 
includes that modifier, the operation is immediately terminated and the 
driver returns a failure status. IO$M_INHRETRY has no effect on power 
failure and timeout recovery. 
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The driver can write up to 16 extended interrecord gaps during the 
error recovery for a write operation. For the TE16, TU45, and TU77, 
writing these gaps can be suppressed by specifying the inhibit extended 
interrecord gap function modifier (IO$M_INHEXTGAP). This modifier is 
ignored for the other magnetic tape drives. 


Streaming Tape Systems 
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Note: 


Streaming tape systems, such as the TK50, TK70,TU80, TU81, TU81-Plus, 
TA81, and TZ30, use the supply and takeup reel mechanisms to control 
tape speed and tension directly, thereby eliminating the need for more 
complex and costly tension and drive components. Streaming tapes have a 
very simple tape path, much like a home audio reel-to-reel recorder. 


Read and write operations with data check can result in very slow 
performance on streaming tape drives. 


Because the motors driving the reels are low-powered and because there 
is no tape buffering, streaming tape drives are not capable of starting and 
stopping in the interrecord gaps like conventional tape drives. When a 
streaming tape does have to stop, the following events occur: 


1 The tape slowly coasts forward to a stop. 

2 It backs up over a section previously processed. 
3 It halts to await the next command. 
4 


It accelerates so that, when the original interrecord gap is encountered, 
the tape is moving at full speed. 


These steps, allowing the tape to reposition, require approximately one- 
half second to complete on TU8x tapes and about three seconds on TK50 
tapes. If the operating system is not capable of writing to, or reading from, 
a streaming tape drive at a rate that will keep the drive in constant motion 
(streaming) the drive repositions itself when it runs out of commands to 
execute. That produces a situation known as thrashing, in which the 
relatively long reposition times exceed the time spent processing data and 
the result is lower-than-expected data throughput. 


Thrashing is entirely dependent on how fast the system can process 
data relative to the tape drive speed while streaming. Consequently, the 
greatest efficiency is obtained when you provide sufficient buffering to 
ensure continuous tape motion. Some streaming tape drives supported 
by the VMS operating system (TU80, TU81, TU81-Plus, and TA81) are 
dual-speed devices that automatically adjust the tape speed to maximize 
data throughput and minimize thrashing. 


The TK50 writes up to seven filler records to keep the tape in motion. 
These records are ignored when the data is read. 
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6.3 Magnetic Tape Driver Device Information 


You can obtain information on all magnetic tape device characteristics by 
using the Get Device/Volume Information ($GETDVI) system service. (See 
the VMS System Services Reference Manual.) 


$GETDVI returns magnetic tape characteristics when you specify the item 
codes DVI$_DEVCHAR, DVI$_DEVCHAR2, DVI$_DEVDEPEND, and 
DVI$_DEVDEPEND2. Tables 6-2, 6-3, and 6—4 list these characteristics. 
The $DEVDEF macro defines the device-independent characteristics, 

the $MTDEF macro defines the device-dependent characteristics, and 

the $MT2DEF macro defines the extended device characteristics. The 
extended device characteristics apply only to the TU81-Plus. 


Table 6-2 Magnetic Tape Device-Independent Characteristics 


Characteristic’ Meaning 


Dynamic Bits (Conditionally Set) 


DEV$M_AVL Device is online and available. 
DEV$M_FOR Volume is foreign. 

DEV$M_MNT Volume is mounted. 

DEV$M_RCK Perform data check on all read operations. 
DEV$M_WCK Perform data check on all write operations. 


Static Bits (Always Set) 


DEV$M_FOD Device is file-oriented. 

DEV$M_IDV Device is capable of input. 
DEV$M_ODV Device is capable of output. 
DEV$M_SQD Device is capable of sequential access. 


DEV$M_WBC? Device is capable of write-back caching. 


'Defined by the $DEVDEF macro. 
2This bit is located in DVI$_DEVCHAR2. 


Table 6-3 Device-Dependent Information for Tape Devices 


Characteristic’ Meaning 

MT$M_LOST If set, the current tape position is unknown. 

MT$M_HWL lf set, the selected drive is hardware write-locked. 
MT$M_EOT If set, an end-of-tape (EOT) condition was encountered by 


the last operation to move the tape in the forward direction. 
'Defined by the $MTDEF macro. 


(continued on next page) 
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Table 6-3 (Cont.) Device-Dependent Information for Tape Devices 


Characteristic’ Meaning 

MT$M_EOF If set, a tape mark was encountered by the last operation to 
move tape. 

MT$M_BOT If set, a beginning-of-tape (BOT) marker was encountered by 
the last operation to move tape in the reverse direction. 

MT$M_PARITY If set, all data transfers are performed with even parity. If 


clear (normal case), all data transfers are performed with odd 
parity. Only non-return-to-zero-inverted recording at 800 bpi 
can have even parity. 


MT$V_DENSITY Specifies the density at which all data transfer operations are 
MT$S_DENSITY performed. Possible density values are as follows: 
MT$K_GCR_6250 Group-coded recording, 6250 bpi 
MT$K_PE_1600 Phase-encoded recording, 1600 bpi 
MT$K_NRZI_800 Non-return-to-zero-inverted recording, 
800 bpi 
MT$K_BLK_833 Cartridge block mode recording? 
MT$V_FORMAT Specifies the format in which all data transfers are performed. 
MT$S_FORMAT A possible format value is as follows: 


MT$K_NORMAL11 Normal PDP-~11 format. Data bytes 
are recorded sequentially on tape 
with each byte occupying exactly one 
frame. 


'Defined by the $MTDEF macro. 
2Only for the TK50 and TZ30. 


Table 6-4 Extended Device Characteristics for Tape Devices 


Characteristic’ Meaning 


MT2$V_WBC_ENABLE If set, write-back caching is enabled for this unit. 
MT2$V_RDC_DISABLE If set, read caching is disabled for this unit. 


'Defined by the $MT2DEF macro. Only for the TU81-Plus. Initial device status will show both 
of these bits cleared; write-back caching will be disabled, read caching will be enabled. 


DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class 
names, which are defined by the $DCDEF macro. DVI$_DEVBUFSIZ 
returns the buffer size. The buffer size is the default to be used for tape 
transfers (normally 2048 bytes). The device class for magnetic tapes is 
$DCTAPE, and the device type is determined by the magnetic tape model. 
For example, the device type for the TA78 is DT$_TA78, for the TA81 it is 
DT$_TA81. 
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6.4 Magnetic Tape Function Codes 


The VMS magnetic tape driver can perform logical, virtual, and physical 
I/O functions. Foreign-mounted devices do not require privilege to perform 
logical and virtual I/O requests. 


Logical and physical I/O functions to magnetic tape devices allow 
sequential access to volume storage and require only that the requesting 
process have direct access to the device. The results of logical and physical 
I/O operations are unpredictable if an ACP is present. 


Virtual I/O functions require intervention by an ACP and must be executed 
in a prescribed order. The normal order is to create and access a file, write 
information to that file, and deaccess the file. Subsequently, when you 
access tl:e file, you read the information and then deaccess the file. You 
can write over the file when the information it contains is no longer useful 
and the file has expired. 


Any number of bytes (from a minimum of 14 to a maximum of 65,535) 
can be read from or written into a single block by a single request. The 
number of bytes itself has no effect on the applicable quotas (direct I/O, 
buffered I/O, and AST). Reading or writing any number of bytes subtracts 
the same amount from a quota. 


The volume to which a logical or virtual function is directed must be 
mounted for the function actually to be executed. If it is not, either a 
“device not mounted” or “invalid volume” status is returned in the I/O 
status block. 


Table 6-5 lists the logical, virtual, and physical magnetic tape I/O 
functions and their function codes. These functions are described in 
more detail in the following paragraphs. Chapter 1 describes the QIO 
level interface to the magnetic tape device ACP. 


Table 6-5 Magnetic Tape I/O Functions 


Function Code 


lO$_ACCESS 


lO$_ACPCONTROL  P1,[P2],[P3],[P4], [P5] V 


1O$_AVAILABLE 
1O$_CREATE 


Arguments Type’ Function Modifiers Function — 
P1,[P2],[P3],[P4],[P5]  V lIOSM_CREATE Search a tape for a specified 
lO$M_ACCESS file and access the file if found 
and IO$M_ACCESS is set. 
If the file is not found and 
IO$M_CREATE is set, create 
a file at end-of-tape (EOT) 
marker. 
lIO$M_DMOUNT Perform miscellaneous control 
functions.° 
P Clear volume valid bit. 
P1,[P2[,[P3],[P4],[P5] V lOSM_CREATE Create a file. 
l\O$M_ACCESS 


'V = virtual; L = logical; P = physical. 


See Section 1.6.7 for additional information. 


(continued on next page) 
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Table 6-5 (Cont.) 
Function Code 
1O$_DEACCESS 
1O0$_DSE? 
lO$_FLUSH 


1O$_MODIFY 
lO$_PACKACK 
1O$_READLBLK 


1O0$_READPBLK 
lO$_READVBLK 
lO$_REWIND 


lO$_REWINDOFF 


lO$_SENSECHAR 
lO$_SENSEMODE 


lO$_SETCHAR 
lO$_SETMODE 


lO$_SKIPFILE 


Arguments 
P14 ,[P2],{P3],[P4],[P5] 


P14 ,[P2],[P3],[P4],[P5] 


P1,P2 


P1,P2 


P1,P2 


[P1] [P2]° 


[P1}[P2]® 


P1,[P2]° 
P1,[P2]° 


P41 


Magnetic Tape I/O Functions 


Type’ 
V 


Function Modifiers 


IO$M_NOWAIT 


lO$M_DATACHECK® 
IO$M_INHRETRY 
IO$M_REVERSE* 


|O$M_DATACHECK® 
IO$M_INHRETRY 
lO$M_REVERSE* 


lO$M_DATACHECK® 
IO$M_INHRETRY 
IO$M_REVERSE* 


IO$M_INHRETRY 
1O$M_NOWAIT 


IO$M_INHRETRY 


1O$M_NOWAIT 
l1O$M_INHRETRY 


IO$M_INHRETRY 


lIO$M_INHRETRY 
\O$M_NOWAIT® 


Function 


Deaccess a file and, if the file 
has been written, write out 
trailer records. 


Erase a prescribed section of 
the tape. 


Flush the controller cache to 
tape. 


Write user labels. 
Initialize volume valid bit. 
Read logical block. 


Read physical block. 


Read virtual block. 


Reposition tape to the 
beginning-of-tape (BOT) 
marker. 

Rewind and unload the tape 
on the selected drive. 


Sense the tape characteristics 
and return them in the I/O 
status block. 


Sense the tape characteristics 
and return them in the I/O 
status block. 


Set tape characteristics for 
subsequent operations. 


Set tape characteristics for 
subsequent operations. 


Skip past a specified number 
of tape marks in either a 
forward or reverse direction. 





'V = virtual; L = logical; P = physical. 
2Only for TMSCP drives, TZK50, and TZ30. 


3Not for TS04 and TU8O. 


4Not for TUK50 and TQK5O0. 


5Only for RV20, TAQO, TK70, and TU81-Plus drives. 


8The Pi and P2 arguments for |O$_SENSEMODE and |O$_SENSECHAR and the P2 argument for |O$_SETMODE and 
1O$_SETCHAR are for TMSCP drives only. 
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Table 6-5 (Cont.) Magnetic Tape I/O Functions 


Function Code 
10$_SKIPRECORD 


lO$_UNLOAD 


lO$_WRITELBLK 


lO$_WRITEOF 


10$_WRITEPBLK 


1O$_WRITEVBLK 


Arguments 

P1 L 
L 

P1,P2 L 
L 

P1,P2 P 

P1,P2 V 


'V = virtual; L = logical; P = physical. 


3Not for TS04 and TU80. 


5Only for RV20, TA90, TK70, and TU81-Plus drives. 
STakes no arguments; valid only for TMSCP drives, TZK50, and TZ30. 


7Only for TE16, TU45, and TU77. 


Type’ 
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Function Modifiers 


1O$M_INHRETRY 
lO$M_NOWAIT® 


lO$M_INHRETRY 
l\O$M_NOWAIT 


lO$M_ERASE® 
lO$M_DATACHECK? 
lO$M_INHRETRY 
IO$M_INHEXTGAP’ 
\O$M_NOWAIT® 


IO$M_INHRETRY 
lO$M_INHEXTGAP’ 
lO$M_NOWAIT® 


l\O$M_ERASE® 
IO$M_DATACHECK? 
lO$M_INHRETRY 
IO$M_INHEXTGAP” 
lO$M_NOWAIT® 


lO$M_DATACHECK?® 
1\O$M_INHRETRY 
lO$M_INHEXTGAP’ 
lOSM_NOWAIT® 


Function 


Skip past a specified number 
of blocks in either a forward 
or reverse direction. 


Rewind and unload the tape 
on the selected drive. 


Write logical block. 


Write an extended interrecord 
gap followed by a tape mark. 


Write physical block. 


Write virtual block. 


The function-dependent arguments for IO$_CREATE, IO0$_ACCESS, 
I0$_DEACCESS, IO$_MODIFY, I0$_ACPCONTROL are as follows: 


P1—The address of the file information block (FIB) descriptor. 


P2—Optional. The address of the file name string descriptor. If 
specified with IO$_ACCESS, the name identifies the file being sought. 
If specified with I0$_CREATE, the name is the name of the created 


file. 


P3—Optional. The address of the word that is to receive the length of 
the resultant file name string. 


P4—Optional. The address of a descriptor for a buffer that is to receive 
the resultant file name string. 


P5—Optional. The address of a list of attribute descriptors. If specified 
with IO0$_ACCESS, the attributes of the file are returned to the user. 
If specified with IO$_CREATE, P5 is the address of the attribute 
descriptor list for the new file. All file attributes for IO$_MODIFY are 


ignored. 
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See Chapter 1 for more information on these functions. 


The function-dependent arguments for IO$_READVBLK, 
I0$_READLBLK, I0$_READPBLK, I0$_WRITEVBLK, 
I0$_WRITELBLK, and I0$_WRITEPBLK are as follows: 


e P1—tThe starting virtual address of the buffer that is to receive the 
data in the case of a read operation; or, in the case of a write operation, 
the virtual address of the buffer that is to be written on the tape. 


e P2—The length of the buffer specified by P1 


The function-dependent argument for IO$_SKIPFILE and 
I0$_SKIPRECORD is: 


e Pi—The number of tape marks to skip over in the case of a skip file 
operation; or, in the case of a skip record operation, the number of 
blocks to skip over. If a positive number is specified, the tape moves 
forward; if a negative number is specified, the tape moves in reverse. 
(The maximum number of tape marks or records that P1 can specify is 
32,767.) 


The following example shows the correct method of defining the P1 
parameter in a IO$_SKIPRECORD QIO. 


TAPE CHAN: 


- WORD 0 
IOSB: - WORD 0 
- WORD 0 
- LONG 0 


DEVICE: .ASCID /$127SMUAO0: / 
RECORD: .LONG 2000 
.PSECT CODE, EXE, NOWRT 
. ENTRY MT IO, *M<> 
SASSIGN_S CHAN=TAPE_ CHAN, ~ 
DEVNAM=DEVICE 
BLBC RO, EXIT_ERROR 


S$QIOW_S CHAN=TAPE_CHAN, - 
FUNC=#10$ SKIPRECORD, - 
LOSB=IOSB, - 

P1=RECORD 

BLBC RO, EXIT ERROR 

SEXIT_S RO 


EXIT ERROR: 


SEXIT_S RO 
-END MT IO 


6.4.1 


Read 
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The read function reads data into a specified buffer in the forward or 
reverse direction starting at the next block position. 


The VMS operating system provides the following read function codes: 
e I0$_READVBLK—Read virtual block 

¢ I10$ READLBLK—Read logical block 

¢ I0$_READPBLK—Read physical block 


If a read virtual block function is directed to a volume that is mounted 
foreign, it is converted to a read logical block function. If a read virtual 
block function is directed to a volume that is mounted structured, the 
volume is handled the same way as a file-structured device. 


Two function-dependent arguments are used with these codes: P1 and P2. 
These arguments are described in Section 6.4. 


If the read function code includes the reverse function modifier 
(IO$M_REVERSE), the drive reads the tape in the reverse direction 
instead of the forward direction. IO$M_REVERSE cannot be specified for 
the TUK50 and TQK50 devices. 


The data check function modifier (IO$M_DATACHECK) can be used with 
all read functions. If this modifier is specified, a data check operation is 
performed after the read operation completes. (The drive performs a space 
reverse or space forward between the read and data check operations.) A 
data check operation is also performed if the volume that was read, or the 
volume on which the file resides (virtual read), has the characteristic “data 
check all reads.” Furthermore, a data check is performed after a virtual 
read if the file has the attribute “data check on read.” The TS04 and TU80 
tape drives do not support the data check function. 


For read physical block and read logical block functions, the drive returns 
the status SS$_NORMAL (not end-of-tape status) if either of the following 
conditions occurs and no other error condition exists: 


e¢ The tape is positioned past the end-of-tape (EOT) position at the start 
of the read (forward or reverse) operation. 


¢ The tape enters the EOT region as a result of the read (forward) 
operation. 


The transferred byte count reflects the actual number of bytes read. 


If the drive reads a tape mark during a logical or physical read operation 
in either the forward or reverse direction, any of the following conditions 
can return an end-of-file status: 


e¢ The tape is positioned past the EOT position at the start of the read 
operation. 


e The tape enters the EOT region as a result of the read operation. 


e The drive reads a tape mark as a result of a read operation but the 
tape does not enter the EOT region. 
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Write 
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An end-of-file status is also returned if the drive attempts a read operation 
in the reverse direction when the tape is positioned at the beginning-of- 
tape (BOT) marker. All conditions that cause an end-of-file status result 
in a transferred byte count of zero. 


If the drive attempts to read a block that is larger than the specified 
memory buffer during a logical or physical read operation, a data overrun 
status is returned. The buffer receives only the first part of the block. On 
a read in the reverse direction (on drives other than the TK50 and TZ30) 
the buffer receives only the latter part of the block. The transferred byte 
count is equal to the actual size of the block. Read reverse starts at the 
top of the buffer. Thus, the start of the block is at P1 plus P2 minus the 
length read. The TUK50 and TZ30 cannot actually perform read reverse 
operations; they must be simulated by the driver. Therefore, the data 
returned are those that would have been returned had the block been read 
in the forward direction. 


It is not possible to read a block that is less than 14 bytes in length. 
Records that contain less than 14 bytes are termed “noise blocks” and are 
completely ignored by the driver. 


The write function writes data from a specified buffer to tape in the 
forward direction starting at the next block position. 


The VMS operating system provides the following write function codes: 
¢ I0$_WRITEVBLK—Write virtual block 

¢ I0$ WRITELBLK—Write logical block 

¢ I0$ WRITEPBLK—Write physical block 


If a write virtual block function is directed to a volume that is mounted 
foreign, the function is converted to a write logical block. If a write virtual 
block function is directed to a volume that is mounted structured, the 
volume is handled the same way as a file-structured device. 


Two function-dependent arguments are used with these codes: P1 and P2. 
These arguments are described in Section 6.4. 


The IO$M_ERASE function modifier can be used with the 
10$_WRITELBLK and I0$_WRITEPBLK function codes to erase a user- 
selected part of a tape. This modifier propagates an erase pattern of all 
zeros from the current tape position to 10 feet past the EOT position and 
then rewinds to the BOT marker. 


The data check function modifier (IO$M_DATACHECK) can be used with 
all write functions. If this modifier is specified, a data check operation 

is performed after the write operation completes. (The drive performs 

a space reverse between the write and the data check operations.) The 
driver forces a data check operation when an error occurs during a 

write operation. This ensures that the data can be reread. A data check 
operation is also performed if the volume written, or the volume on which 
the file resides (virtual write), has the characteristic “data check all 
writes.” Furthermore, a data check is performed after a virtual write if 


6.4.3 


6.4.4 


Rewind 


Skip File 
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the file has the attribute “data check on write.” The TS04 and TU80 tape 
drives do not support the data check function. 


If the IO$M_NOWAIT function modifier is specified, write-back caching 
is enabled on a per command basis. IO$M_NOWAIT is applicable only to 
TU81-Plus drives. 


If the drive performs a write physical block or a write logical block 
operation, an EOT status is returned if either of the following conditions 
occurs and no other error condition exists: 


e The tape is positioned past the EOT position at the start of the write 
operation. 


e The tape enters the EOT region as a result of the write operation. 


The transferred byte count reflects the size of the block written. It is not 
possible to write a block less than 14 bytes in length. An attempt to do so 
results in the return of a bad parameter status for the QIO request. 


The rewind function repositions the tape to the beginning-of-tape (BOT) 
marker. If the IO$M_NOWAIT function modifier is specified, the I/O 
operation is completed when the rewind is initiated. Otherwise, I/O 
completion does not occur until the tape is positioned at the BOT marker. 
IO0$_REWIND has no function-dependent arguments. 


The skip file function skips past a specified number of tape marks in 
either a forward or reverse direction. A function-dependent argument (P1) 
is provided to specify the number of tape marks to be skipped, as shown 
in Figure 6-1. If a positive file count is specified, the tape moves forward; 
if a negative file count is specified, the tape moves in reverse. (The actual 
number of files skipped is returned as an unsigned number in the I/O 
status block.) 


Figure 6-1 lO$ SKIPFILE Argument 


31 16 15 0 
P1: Not Used File Count 
ZK-0671-GE 
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Skip Record 


6.4.5.1 
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Only tape marks (when the tape moves in either direction) and the BOT 
marker (when the tape moves in reverse) are counted during a skip file 
operation. The BOT marker terminates a skip file function in the reverse 
direction. The end-of-tape (EOT) marker does not terminate a skip file 
function in either the forward or reverse direction. A negative skip file 
function leaves the tape positioned just before a tape mark (at the end of 
a file) unless the BOT marker is encountered, whereas a positive skip file 
function leaves the tape positioned just past the tape mark. 


A skip file function in the forward direction can also be terminated if two 
consecutive tape marks are encountered. Section 6.4.5.1 describes this 
feature. 


The skip record function skips past a specified number of physical tape 
blocks in either a forward or reverse direction. A device- or function- 
dependent argument (P1) specifies the number of blocks to skip, as 
shown in Figure 6-2. If a positive block count is specified, the tape moves 
forward; if a negative block count is specified, the tape moves in reverse. 
The actual number of blocks skipped is returned as an unsigned number 
in the I/O status block. If a tape mark is detected, the count is the number 
of blocks skipped, plus 1 (forward tape motion) or minus 1 (reverse tape 
motion). 


Figure 6-2 1O$ SKIPRECORD Argument 


31 16 15 0 
P1: Not Used Block Count 
ZK-0672-GE 


A skip record operation is terminated by the end-of-file marker when the 
tape moves in either direction, by the BOT marker when the tape moves 
in reverse, and by the EOT marker when the tape moves forward. 


A skip record function in the forward direction can also be terminated if 
the tape was originally positioned between two tape marks. Section 6.4.5.1 
describes this feature. 


Logical End-of-Volume Detection 


A skip file or skip record operation is terminated when two consecutive 
tape marks are encountered when the tape moves in the forward direction. 


6.4.6 


6.4.7 


Write End-of-File 


Rewind Offline 
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After the operation terminates, the tape remains positioned between the 
two tape marks that were detected. The I/O status block (IOSB) returns 
the status SS$ ENDOFVOLUME and the actual number of files (or 
records) skipped during the operation prior to the detection of the second 
tape mark. The skip count is returned in the high-order word of the first 
longword of the IOSB. 


Subsequent skip record (or skip file) requests terminate immediately when 
the tape is positioned between the two tape marks, producing no net tape 
movement and returning the SS$_ENDOFVOLUME status with a skip 
count of zero. 


To move the tape beyond the second tape mark, you must employ another 
I/O function. For example, the IO$_READLBLK function, if issued after 
receipt of the SS$_ENDOFVOLUME status return, terminates with an 
SS$_ENDOFFILE status and with the tape positioned just past the second 
tape mark. From this new position, other skip functions could be issued 
to produce forward tape motion (assuming there is additional data on the 
tape). 


If three consecutive tape marks are encountered during a skip file function, 
you must issue two IO$_READLBLK functions, the first to get the 
SS$_ENDOFFILE return, the second to position the tape past the third 
tape mark. 


The write-end-of-file function writes an extended interrecord gap (of 
approximately 3 inches for non-return-to-zero-inverted (NRZI) recording 
and 1.5 inches for phase-encoded (PE) recording) followed by a tape mark. 
No device- or function-dependent arguments are used with IO$_WRITEOF. 


An end-of-tape (EOT) status is returned in the I/O status block if either of 
the following conditions is present and no other error conditions occur: 


¢ A write end-of-file function is executed while the tape is positioned 
past the EOT marker. 


e A write end-of-file function causes the tape position to enter the EOT 
region. 


The rewind offline function rewinds and unloads the tape on the selected 
drive. If the IO$M_NOWAIT function modifier is specified, the I/O 
operation is completed as soon as the rewind operation is initiated. No 
device- or function-dependent arguments are used with IO$_REWINDOFF. 
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Unload 


The unload function rewinds and unloads the tape on the selected drive. 
The unload function is functionally the same as the rewind offline function. 
If the IO$M_NOWAIT function modifier is specified, the I/O operation is 
completed as soon as the rewind operation is initiated. No device- or 
function-dependent arguments are used with IO$_UNLOAD. 


Sense Tape Mode 
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The sense tape mode function senses the current device-dependent and 
extended device characteristics (see Tables 6-3 and 6-4). 


The VMS operating system provides the following function codes: 
¢ JO$_SENSEMODE—Sense mode 
¢ I0$_SENSECHAR—Sense characteristics 


Sense mode requires logical I/O privilege. Sense characteristics requires 
physical I/O privilege. For TMSCP drives the sense mode function returns 
magnetic tape information in a user-supplied buffer, which is specified by 
the following function-dependent arguments: 


e P1—Optional. Address of a user-supplied buffer. 
e P2—Optional. Length of a user-supplied buffer. 


If P1 is not zero, the sense mode buffer returns the tape characteristics. 
(If P2=8, the second longword of the buffer contains the device-dependent 
characteristics. If P2=12, the second longword contains the device- 
dependent characteristics and the third longword contains the tape 
densities that the drive supports and the extended tape characteristics.) 
The extended characteristics are identical to the information returned by 
DVI$_DEVDEPEND2 (see Table 6—4). Figure 6-3 shows the contents of 
the P1 buffer. | 


Regardless of whether the P1 buffer is specified, the I/O status block 
returns the device-dependent characteristics in the second longword 
(see Figure 6-6). These characteristics are identical to the information 
returned by DVI$_DEVDEPEND (see Table 6~3 in Section 6.3). 


6.4.10 Set Mode 
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Figure 6-3 Sense Mode P1 Buffer 


P2=8: 
31 16 15 8 7 0 


Tape Characteristics * 


* From UCB$L_DEVDEPEND 





P2=12: 
31 16 15 8 7 0 


Tape Characteristics * 
Extended Tape Characteristics * * Supported Densities * * 


* From UCB$L_DEVDEPEND 
“* From UCB$L_DEVDEPND2 













ZK-4854-GE 


Set mode operations affect the operation and characteristics of the 
associated magnetic tape device. The VMS operating system defines 
two types of set mode functions: set mode and set characteristics. 


Set mode requires logical I/O privilege. Set characteristics requires 
physical I/O privilege. The following function codes are provided: 


¢ I0$_SETMODE—Set mode 

¢ I0$ SETCHAR—Set characteristics 

These functions take the following device- or function-dependent 
arguments (other arguments are ignored): 

¢ Pi—The address of a characteristics buffer 


¢ P2—Optional. The length of the characteristics buffer. Default is eight 
bytes. If a length of 12 bytes is specified, the third longword (which is 
for TMSCP drives only) specifies the extended tape characteristics. 


6-23 


Magnetic Tape Drivers 
6.4 Magnetic Tape Function Codes 


Figure 6—4 shows the P1 characteristics buffer for IO$_SETMODE. 
Figure 6-5 shows the same buffer for IO$_SETCHAR. 


Figure 6-4 Set Mode Characteristics Buffer 


P2=8: 
31 16 15 0 


Tape Characteristics 











31 16 15 0 


Tape Characteristics 
Extended Tape Characteristics 


ZK-4856-GE 
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Figure 6-5 Set Characteristics Buffer 


P2=8: 
31 16 15 8 7 0 


Tape Characteristics 












P2=12: 
31 16 15 8 7 0 
Tape Characteristics 


Exended Tape Chara 


ZK-4855-GE 


The first longword of the P1 buffer for the set characteristics function 
contains information on device class and type, and the buffer size. The 
device class for tapes is DC$_TAPE. 


The $DCDEF macro defines the device type and class names. The buffer 
size is the default to be used for tape transfers (this default is normally 
2048 bytes). 


The second longword of the P1 buffer for both the set mode and set 
characteristics functions contains the tape characteristics. Table 6-6 lists 
the tape characteristics and their meanings. The $MTDEF macro defines 
the symbols listed. If P2=12, the third longword contains the extended 
tape characteristics for TMSCP drives, which are listed in Table 6-7. The 
extended tape characteristics are defined by the $MT2DEF macro and are 
identical to the information returned by DVI$_DEVDEPEND2. 


6—25 


Magnetic Tape Drivers 
6.4 Magnetic Tape Function Codes 


6-26 


Table 6-6 Set Mode and Set Characteristics Magnetic Tape 


Characteristics 
Characteristic’ Meaning 
MT$M_PARITY If set, all data transfers are performed with even parity. If 


clear (normal case), all data transfers are performed with 
odd parity. Even parity can be selected only for non-return- 
to-zero-inverted recording at 800 bpi. Even parity cannot 
be selected for phase-encoded recording (tape density is 
MT$K_PE_1600) or group-coded recording (tape density is 
MT$K_GCR_6250) and is ignored. 

MT$V_DENSITY Specifies the density at which all data transfers are 

MT$S_DENSITY performed. Tape density can be set only when the selected 
drive’s tape position is at the BOT marker. Possible density 
values are as follows: 


MT$K_DEFAULT Default system density. 
MT$K_GCR_6250 Group-coded recording, 6250 bpi. 


MT$K_PE_1600 Phase-encoded recording, 1600 bpi. 
MT$K_NRZI_800 Non-return-to-zero-inverted recording, 
800 bpi. 
MT$K_BLK_833 Cartridge block mode recording’. 
MT$V_FORMAT Specifies the format in which all data transfers are performed. 
MT$S_FORMAT Possible format values are as follows: 


MT$K_DEFAULT Default system format. 


MT$K_NORMAL11 Normal PDP-11 format. Data bytes 
are recorded sequentially on tape 
with each byte occupying exactly one 
frame. 


'Defined by the $MTDEF macro 
2Only for the TK50 and TZ30 


Table 6-7 Extended Device Characteristics for Tape Devices 
Characteristic! Meaning 


MT2$V_WBC_ENABLE Enable write-back caching on a per unit basis. 
MT2$V_RDC_DISABLE Disable read caching on a per unit basis. 


'Defined by the $MT2DEF macro. Only for TU81-Plus drives. 


Application programs that change specific magnetic tape characteristics 
should perform the following steps, as shown in Example 6-2 in 
Section 6.6: 


1 Use the I0$ SENSEMODE function to read the current 
characteristics. 


Modify the characteristics. 
Use the set mode function to write back the results. 
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Failure to follow this sequence will result in clearing any previously set 
characteristic. 


6.4.11 Data Security Erase 


The data security erase function erases all data from the current position 
of the volume to 10 feet beyond the EOT reflective strip and then rewinds 
the tape to the BOT marker. It is a physical I/O function and requires 
the access privilege necessary to perform physical I/O functions. It is 
applicable only for the TA78, TU78, TA81, TK50, TU81, TU81-Plus, and 
TZ30 drives. The following function code is provided: 


¢ I0$_DSE 


If the function is issued when a tape is positioned at the BOT marker, all 
data on the tape will be erased. 


10$_DSE takes no device- or function-dependent arguments. 


6.4.12 Pack Acknowledge 


6.4.13 Available 


6.4.14 Flush 


The pack acknowledge function sets the volume valid bit for all magnetic 
tape devices. It is a physical I/O function and requires the access privilege 
to perform physical I/O. The following function code is provided: 


¢ IO$_PACKACK 


This function code takes no function-dependent arguments. 


10$_PACKACK must be the first function issued when a volume is placed 
in a magnetic tape drive. IO$_PACKACK is issued automatically when 
the DCL commands INITIALIZE or MOUNT are issued. 


The available function clears the volume valid bit for all magnetic tape 
drives, that is, it reverses the function performed by the pack acknowledge 
function (see Section 6.4.12). A rewind of the tape is performed (applicable 
to all tape drives). No unload function is issued to the drive. The following 
function code is provided: 


e I0$_AVAILABLE 


This function takes no function-dependent arguments. 


The flush function is used to ensure that all previously issued cached 
commands have fully completed. Normally, hosts use this function to 
establish or maintain synchronization with write-back cached commands 
issued to the specified tape unit. The I/O request does not complete until 
all cached data is written successfully to the media in the exact order that 
the user specified. 
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e I0$_FLUSH 


This function code takes no function-dependent arguments. 





6.5 I/O Status Block 


The I/O status block (IOSB) for QIO functions on magnetic tape devices 
is shown in Figure 6-6. Appendix A lists the status returns for these 
functions. (The VMS System Messages and Recovery Procedures Reference 
Manual provides explanations and suggested user actions for these 
returns.) Table 6—3 (in Section 6.3) lists the device-dependent data 
returned in the second longword. The IO$_SENSEMODE function can 
be used to return that data. 


Figure 6-6 IOSB Contents 


31 16 15 0 


Device—Dependent Data 
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The byte count is the actual number of bytes transferred to or from the 
process buffer or the number of files or blocks skipped. (Ifa 
IO$_SKIPRECORD function is terminated by the detection of a tape mark, 
the count returned in the IOSB is an unsigned number reflecting the 
number of blocks skipped, plus 1. 


6.6 Magnetic Tape Driver Programming Examples 


This section presents three magnetic tape driver programming examples. 


6.6.1. Magnetic Tape Data Program Example 
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Example 6-1 shows how data is written to and read from magnetic tape. 
In the example, QIO operations are performed through the magnetic 
tape ACP. These operations could have been performed directly on the 
device using a magnetic tape driver. However, this would have involved 
additional programming such as writing header labels and trailer labels. 
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Example 6-1 Magnetic Tape Data Program Example 





KAKKKKKEKKKKKKEKKEKKE KKK KKK KKK KKK KKK KEKKKK KKK KKK KK KKK KKK KKKKKKKKEKKKKRKKKEKKK 


.TITLE MAGTAPE PROGRAMMING EXAMPLE 
.IDENT /01/ 


; Define necessary symbols. 


SFIBDEF ;Define file information block 
;symbols 
SIODEF ;Define I/O function codes 


+; Allocate storage for the necessary data structures. 


7 Allocate magtape device name string and descriptor. 


TAPENAME : ; 
. LONG 20$-10$ ;Length of name string 
. LONG 10$ ;Address of name string 
10S: -ASCII /TAPE/ ;Name string 
20S: ;Reference label 


+ Allocate space to store assigned channel number. 
TAPECHAN: ; 

- BLKW 1 ;Tape channel number 
? 
; Allocate space for the I/O status quadword. 
IOSTATUS: ; 

. BLKQ 7 ;I/O status quadword 
; Allocate storage for the input/output buffer. 


° 
, 


BUFFER: ; 
.REPT 256 jInitialize buffer to 
-ASCII /A/ ;contain ‘A’ 
- ENDR ; 


Now define the file information block (FIB), which the ACP uses 
in accessing and deaccessing the file. Both the user and the ACP 
supply the information required in the FIB to perform these 

; functions. 


Ne Ne Ne Ne 





(continued on next page) 
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FIB DESCR: ;Start of FIB 
- LONG ENDFIB-FIB ;Length of FIB 
. LONG FIB ;Address of FIB 
FIB: -LONG FIBS$M _WRITE!FIBS$M_NOWRITE ;Read/write access allowed 
. WORD 0,0,0 ;File ID 
. WORD 0,0,0 ;Directory ID 
. LONG 0 7 Context 
.- WORD 0 ;Name flags 
.» WORD 0 ;Extend control 
ENDFIB: 7;Reference label 


; Now define the file name string and descriptor. 


° 
7 


NAME _DESCR: ; 

-LONG END_NAME-NAME 7File name descriptor 

. LONG NAME ;Address of name string 
NAME: -ASCII “MYDATA.DAT;1" ;File name string 
END_NAME: ;Reference label 


’ 
KRREKKEKKEKKKKE KK KEKE KKEKRKEKKKKEKKK ERK KKK KKK KKK KKKKKRKREKKEKKEKKEKKKKKKKKKRKEKEKKR 


“se SN 


Start Program 


KEKKKKKRKRKKKEKKKKKKEKRKRKKRKKRERKEKKRKEKRKERKE KEKE KRKKRKRKKEKKEKKRKRKRKKKKKKRRKEKKREKRKKERK 


“eo Ne Ne Ne 


The program first assigns a channel to the magnetic tape unit and 
then performs an access function to create and access a file called 
MYDATA.DAT. Next, the program writes 26 blocks of data (the letters 
of the alphabet) to the tape. The first block contains all A’s, the 
; next, all B’s, and so forth. The program starts by writing a block of 
; 256 bytes, that is, the block of A’s. Each subsequent block is reduced 
; in size by two bytes so that by the time the block of 2’s is written, 
the size is only 206 bytes. The magtape ACP does not allow the reading 
of a file that has been written until one of three events occurs: 

1. The file is deaccessed. 

2. The file is rewound. 

3. The file is backspaced. 
In this example the file is backspaced zero blocks and then read in 
reverse (incrementing the block size every block); the data is 
checked against the data that is supposed to be there. If no data 
errors are detected, the file is deaccessed and the program exits. 


=e “Ne ‘Ne Ne 


‘se Se Ye No Ve 


‘Ne Ne Ne Ne 


-ENTRY MAGTAPE EXAMPLE, “M<R3,R4,R5,R6,R7,R8> 


=e 


First, assign a channel to the tape unit. 


“ee Ne 


SASSIGN_S TAPENAME, TAPECHAN 7Assign tape unit 
CMPW #SS$_NORMAL, RO ; Success? 
BSBW ERRCHECK 7Find out 


=e (Ne 


Now create and access the file MYDATA.DAT. 





(continued on next page) 
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’ 


. 
, 


SQIOW_S CHAN=TAPECHAN, - ;Channel is magtape 
FUNC=#1I0$_ CREATE! IOSM_ACCESS! IO$M_CREATE, -;Function 
a zis create 


IOSB=IOSTATUS, - ;Address of I/O status 
= sword 
P1=FIB_DESCR, - ;FIB descriptor 
P2=#NAME_ DESCR ;Name descriptor 

CMPW #SS$ NORMAL, RO Success? 

BSBW ERRCHECK 7Find out 


LOOP1 consists of writing the alphabet to the tape (see previous 
description). 


MOVL #26,R5 7Set up loop count 
MOVL #256,R3 ;Set up initial byte count 
ein RS 
LOOP1: 7;Start of loop 
SQIOW_S CHAN=TAPECHAN, - ;Perform QIOW to tape channel 
FUNC=#1I0$ WRITEVBLK, - ;Function is write virtual 
= zblock 
P1=BUFFER, - ;Buffer address 
P2=R3 ;Byte count 
CMPW #SS$ NORMAL, RO ; Success? 
BSBW ERRCHECK ;Find out 


’ 
. 
tA 


° 
’ 


Now decrement the byte count in preparation for the next write 
operation and set up a loop count for updating the character 
written; LOOP2 performs the update. 


SUBL2 #2,R3 ;Decrement byte count for 
jnext write 

MOVL R3,R8 ;Copy byte count to R8 for 
;LOOP2 count 

MOVAL BUFFER, R7 ;Get buffer address in R7 

LOOP2: INCB (R7)+ ;Increment character 

SOBGTR R8,LOOP2 ;Until finished 

SOBGTR R5,LOOP1 ;Repeat LOOP1 until alphabet 
; complete 


se SNe Ne “oe 


ue 


Ne Ne Ne Ne Neo Ne Ne 


The alphabet is now complete. Fall through LOOP1 and update the 
byte count so that it reflects the actual size of the last block 
written to tape. 


ADDL2 #2,R3 ;Update byte count 


The tape is now read, but first the program must perform one of 

the three functions described previously before the ACP allows 

read access. The program performs an ACP control function, 
specifying skip zero blocks. This is a special case of skip reverse 
and causes the ACP to allow read access. 





(continued on next page) 


6-31 


Magnetic Tape Drivers 


6.6 Magnetic Tape Driver Programming Examples 


Example 6—1 (Cont.) Magnetic Tape Data Program Example 





CLRL FIB+PIB$L_CNTRLVAL 

MOVW 

$QIOW_S CHAN=TAPECHAN, - 
FUNC=#10$ ACPCONTROL, - 
P1=FIB_DESCR 

CMPW § #SS$_NORMAL, RO 

BSBW  ERRCHECK 


; Read the file 


° 
’ 


in reverse. 


;Set up to space zero blocks 


#FIBSC_SPACE,FIB+FIBSW_CNTRLFUNC ;Set up for space 


; function 

;Perform QIOW to tape channel 
;Perform an ACP control 

; function 

;Define the FIB 

; Success? 

;Find out 


MOVL #26,R5 ;Set up loop count 
MOVB #°A/2Z/,R6 ;Get first character in R6 
LOOP3: ; 

MOVAL BUFFER, R7 ;And buffer address to R7 

SQIOW_S CHAN=TAPECHAN, - ;Channel is magtape 
FUNC=#10$_ READVBLK! IO$M_REVERSE, - ;Function is read 
zs ;reverse 
IOSB=IOSTATUS, - ;Define I/O status quadword 
P1=BUPFER, - ;And buffer address 
P2=R3 7R3 bytes 

CMPW #SS$_NORMAL, RO ;Success? 

BSBW ERRCHECK 7;Find out 


; Check the data read to verify that it 


. 
’ 


MOVL R3,R4 
CHECKDATA: 
CMPB (R7) +, R6 
BNEQ MISMATCH 
SOBGTR R4,CHECKDATA 
DECB R6 
ADDL2 #2,R3 
SOBGTR R5,LOOP3 


; Now deaccess the file. 


SQIOW_S CHAN=TAPECHAN, - 
FUNC=#I0O$_ DEACCESS, - 
IOSB=IOSTATUS 


; Deassign the channel and exit. 


° 
, 


EXIT: SDASSGN_S CHAN=TAPECHAN 


RET 


; If an error had been detected, 
7 generate an error message here. 
; program simply exits. 


matches the data written. 


;Copy R3 to R4 for loop count 


a 

7;Check each character 

;Iif error, print message 
;Continue until finished 

;Go through alphabet in reverse 
;Update byte count by 2 for 
s;next block 

;Read next block 


;Channel is magtape 
;Deaccess function 
71/0 status 


;Deassign channel 
7;Exit 


a program would normally 
But for this example the 
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MISMATCH: 
BRB EXIT 
ERRCHECK: 
BNEQ EXIT 
RSB 


- END MAGTAPE EXAMPLE 


° 
, 


; Exit 


. 
, 


;If not success, exit 
;Otherwise, return 


Magnetic Tape Device Characteristic Program Example 


Example 6-2 illustrates the recommended sequence for changing a 

device characteristic. Retrieve the current characteristics using a 
I0$_SENSEMODE request, set the new characteristics bits, and then use 
10$_SETMODE to set the new characteristics. 


Example 6-2 Device Characteristic Program Example 


SQIOW_S - 
FUNC = #I0$ SENSEMODE, - 
CHAN = CHANNEL, - 
IOSB = IO STATUS, - 
P1 = BUFFER, - 
= #12 


P2 
(Check for errors) 


(Set desired characteristics bits) 


SQIOW_S - 
FUNC = #1I10$_SETMODE, - 
CHAN = CHANNEL, - 
TOSB = TO STATUS; = 
Pl = BUFFER, - 
P2 = #12 


(Check for errors) 


Ne “Se Ne Ne Ne Ne 


‘Ne Ne Ne Ne Ne Ne 


Get current characteristics. 
- Sensemode 

- Channel 

- TIOSB 

- User buffer supplied 

- Buffer length = 12 


Set new characteristics. 
- Set Mode 

- Channel 

- IOSB 

- User buffer address 

- Buffer length = 12 
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Set Mode and Sense Mode Program Example 


Example 6-3 shows ways of specifying sense mode and set mode, both 
with and without a user buffer specified, and with user buffers of different 
lengths. 


Example 6-3 Set Mode and Sense Mode Program Example 





-PSECT IMPURE, NOEXE, NOSHR 
SIODEF 
DEVICE_NAME: ; Name of device 
-ASCID /MUAO/ ; 
CHANNEL: ; VMS channel to device 
- WORD 0 ; 
BUFFER: .BLKL 2 ; Set/Sense characteristics 
; buffer 
IO STATUS: ; Final I/O status 
- QUAD 0 ; 
-PSECT CODE, RD, NOWRT, EXE 
. ENTRY MAIN, “M<> 
SASSIGN_S - # Assign a channel to device 
DEVNAM = DEVICE NAME, - ; 
CHAN = CHANNEL ; 
BSBW ERR_CHECK2 ; Check for errors 
SQIOW_S - ; Get current characteristics 
FUNC = #I10$ SENSEMODE,-; No user buffer supplied 
CHAN = CHANNEL, ~ ; 
IOSB = IO_STATUS ; 
BSBW ERR_CHECK ; Check for errors 
SQIOW_S - ; Get current characteristics 
FUNC = #I10$ SENSEMODE,-; User buffer supplied, length 
CHAN = CHANNEL, - ; defaulted 
IOSB = IO STATUS, - ; 
Pl = BUFFER ; 
BSBW ERR_CHECK 7 Check for errors 
SQIOW_S - ; Get current characteristics 
FUNC = #I0$_ SENSEMODE,-; User buffer supplied, length 
CHAN = CHANNEL, - ; = 8 
IOSB = IO_ STATUS, - ; 
Pl = BUFFER, - ; 
P2 = #8 ; 
BSBW ERR_CHECK ; Check for errors 





(continued on next page) 
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S$QIOW_S - ; Get extended characteristics 
FUNC = #10$ SENSEMODE,-; User buffer supplied, length 
CHAN = CHANNEL, — ; = 12 
IOSB = IO STATUS, - ; 
Pl = BUFFER, - ; 
P2 = #12 ; 
BSBW ERR_CHECK ; Check for errors 
SQIOW_S - ; Set new characteristics 
FUNC = #I0$_ SETMODE,- ; Length defaulted 
CHAN = CHANNEL, - ; 
IOSB = IO_STATUS,- ; 
Pl = BUFFER ; 
BSBW ERR_CHECK ; Check for errors 
SQIOW_S - ; Set new characteristics 
FUNC = #10$_SETMODE,- ; Length = 8 
CHAN = CHANNEL, - ; 
IOSB = IO STATUS, - ; 
Pl = BUFFER, - ; 
P2 = #8 ; 
BSBW ERR_CHECK ; Check for errors 
SQIOW_S - ; Set extended characteristics 
FUNC = #I0$ SETMODE,- ; Length = 12 
CHAN = CHANNEL, - ; 
IOSB = IO_ STATUS, - ; 
Pl = BUFFER, - ; 
P2 = #12 ; 
BSBW ERR_CHECK + Check for errors 
RET 
-ENABLE LSB 
ERR_CHECK: 
BLBS IO_STATUS, ERR_CHECK2 ; Continue if good IOSB 
MOVZWL IO STATUS, -(SP) ; Otherwise, set up for stop 
BRB 10$ ; Branch to common code 
ERR_CHECK2: 
BLBS RO, 20$ 7 Continue if good status 
PUSHL RO ; Otherwise, set up for stop 
108: CALLS #1,G*LIBSSTOP ; Stop execution 
208: RSB 


-DISABLE LSB 


- END MAIN 
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Mailbox Driver 


The VMS operating system supports a virtual device, called a mailbox, 
that is used for communication between processes. Mailboxes provide 

a controlled and synchronized method for processes to exchange data. 
Although mailboxes transfer information much like other I/O devices, they 
are not hardware devices. Rather, mailboxes are a software-implemented 
way to perform read and write operations. 


Multiport memory mailboxes function in the same way as regular 
mailboxes. They can also be used by processes on different processors 
connected to an MA780 multiport memory option. 


The Guide to VMS Programming Resources and the VMS System Services 
Reference Manual contain additional information on the use of mailboxes. 





Mailbox Operations 


Table 7-1 lists the different operations that software mailboxes perform. 


Table 7-1 Mailbox Read and Write Operations 


Operation Description 


Receive mail A process initiates a read request to a mailbox 
to obtain data sent by another process. The 
process reads the data if a message was previously 
transmitted to the mailbox. 


Receive notification A process specifies that it be notified through an AST 
of mail when a message is sent to the mailbox. 
Send mail (without A process initiates a write request to another mailbox 
notification of to transmit data to second process. The sending 
receipt) process does not wait until the data is read by the 
receiving process before completing the I/O operation. 
Send mail (with A process initiates a write request to another mailbox 
notification of to transmit data to second process. The sending 
receipt) process waits until the receiving process reads the 


data before completing the I/O operation. 


Reject mail The receiving process reads messages from the 
mailbox, sorts out unwanted messages, and responds 
only to useful messages. 


Creating Mailboxes 


To create a mailbox and assign a channel and logical name to it, a process 
uses the Create Mailbox and Assign Channel ($CREMBX) system service. 

The system enters the logical name in the job logical name table and gives 
it an equivalence name of MBAn, where n is a unique unit number. 
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$CREMBXxX also establishes the characteristics of the mailbox. These 
characteristics include a protection mask, permanence indicator, maximum 
message size, and buffer quota. A mailbox is created as either a temporary 
mailbox or a permanent mailbox; both types of mailboxes require 
privilege to create. Applications and restrictions on use of temporary 

and permanent mailboxes are described in the sections that follow. (See 
the VMS System Services Reference Manual for additional information on 
creating mailboxes.) 


Other processes can assign additional channels to the mailbox using either 
$CREMBX or the Assign I/O Channel ($ASSIGN) system service. The 
mailbox is identified by its logical name both when it is created and when 
it is assigned channels by cooperating processes. 


Figure 7-1 illustrates the use of $CREMBX and $ASSIGN. 


If sufficient dynamic memory for the mailbox data structure is not 
available when a mailbox is created, a resource wait occurs if resource 
wait mode is enabled. 


When a mailbox is created, a certain amount of space is specified for 
buffering messages that have been written to the mailbox, but they have 
not yet been read. The bufquo argument to the $CREMBX system service 
specifies this amount or quota. If that argument is omitted, its value 
defaults to the system generation parameter DEFMBXBUFQUO. 


A message written to a mailbox, in the absence of an outstanding read 
request, is queued to the mailbox, and the size of the message (the QIO 
P2 argument) is subtracted from the available buffering space. After the 
message is read, it is added back to the available buffering space. 


If a process attempts to write to a mailbox that is full or has insufficient 
buffering space, and if the process has resource wait enabled (which is the 
default case), the process is placed in miscellaneous resource wait mode 
until sufficient space is available in the mailbox. If resource wait is not 
enabled, the I/O completes with the status return SS$_MBFULL in the I/O 
status block (IOSB). 


The programming example at the end of this chapter (Example 7-1) 
illustrates mailbox creation and interprocess communication. 


7.1.2 Deleting Mailboxes 


7—2 


As each process finishes using a mailbox, it deassigns the channel using 
the Deassign I/O Channel ($DASSGN) system service. The channel count 
is decremented by 1. The system maintains a count of all channels and 
automatically deletes the mailbox when no more channels are assigned to 
it (that is, when the channel count reaches 0). 


If a mailbox channel is deassigned, all messages sent through that channel 
are deleted unless the IO$M_NOW function modifier was specified with 
the write request. 
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Figure 7-1 Multiple Mailbox Channels 
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Permanent mailboxes must be explicitly deleted using the Delete Mailbox 
($DELMBX) system service. An explicit deletion can occur at any time. 


However, the mailbox is actually deleted when no processes have channels 
assigned to it. 


When a temporary mailbox is deleted, its message buffer quota is returned 


to the process that created it. (No quota charge is made for permanent 
mailboxes.) 


7.1.3 Mailbox Message Format 


There is no standardized format for mailbox messages and none is imposed 
on users. Figure 7-2 shows a typical mailbox message format. Other types 
of messages can take different formats; for an example, see Figure 8—2 in 
Section 8.2.4. 
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Figure 7-2 Typical Mailbox Message Format 
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7.1.4 Mailbox Protection 


Mailboxes (both temporary and permanent) are protected by a code, or 
mask, that is similar to the code used in protecting volumes. As with 
volumes, four types of users (defined by UIC) can gain access to a mailbox: 
SYSTEM, OWNER, GROUP, and WORLD. However, only three types of 
access—logical I/O, read, and write—are meaningful to users of a mailbox. 
Thus, when creating a mailbox, you can specify logical I/O, read, and write 
access to the mailbox separately for each type of user. Logical I/O access 
is required for any mailbox operation. The set protection function modifier 
provides additional control of mailbox access (see Section 7.3.5). 


For additional information on temporary mailboxes and mailbox 
protection, see the description of the $CREMBX system service in the 
VMS System Services Reference Manual. 


7.2 Mailbox Driver Device Information 


You can obtain information on mailbox characteristics by using the Get 
Device/Volume Information (SGETDVI) system service. (See the VMS 
System Services Reference Manual.) 


$GETDVI returns mailbox characteristics when you specify the item code 
DVI$_ DEVCHAR. Table 7~2 lists these characteristics, which are defined 
by the $DEVDEF macro. 
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Table 7-2 Mailbox Characteristics 


Characteristic’ Meaning 
Dynamic Bits (Conditionally Set) 


DEV$M_SHR Device is shareable. 
DEV$M_AVL Device is available. 


Static Bits (Always Set) 


DEV$M_REC Device is record-oriented. 
DEV$M_IDV Device is capable of input. 
DEV$M_ODV Device is capable of output. 
DEV$M_MBX Device is a mailbox. 


‘Defined by the $DEVDEF macro. 


DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device 
type names, which are defined by the $DCDEF macro. The device class 
for mailboxes is DC$_MAILBOX. The device type is DT$_MBX (or DT$_ 
SHRMBxX if the mailbox is a shared memory mailbox). DVI$_DEVBUFSIZ 
returns the buffer size, which is the maximum message size in bytes. 
DVI$_DEVDEPEND returns a longword field in which the two low-order 
bytes contain the number of messages in the mailbox. (The two high-order 
bytes are not used and should be ignored.) 


DVI$_UNIT returns the mailbox unit number. Use of a mailbox to hold a 
termination message for a subprocess or a detached process requires that 


the parent process obtain this number to pass to the mbxunt argument of 
the $CREPRC system service. 


Mailbox Function Codes 


Read 


The VMS mailbox I/O functions are read, write, write end-of-file, and set 
attention AST. 


No buffered I/O byte count quota checking is performed on mailbox I/O 
messages. Instead, the byte count or buffer quota of the mailbox is 
checked for sufficient space to buffer the message being sent. The buffered 
1/O quota and AST quota are also checked. 


Read mailbox functions are used to obtain messages written by other 
processes. The VMS operating system provides the following mailbox 
function codes: 


¢ I0O$ READVBLK—Read virtual block 
¢ JO$ READLBLK—Read logical block 
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Write 
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e I0$_READPBLK—Read physical block 


The following device- or function-dependent arguments are used with 
these codes: 


¢ P1—The starting virtual address of the buffer that is to receive the 
message read. If P2 specifies a zero-length buffer, P1 is ignored. 


¢ P2—tThe size of the buffer in bytes (limited by the maximum message 
size for the mailbox). A zero-length buffer may be specified. If a 
message longer than the buffer is read, the alternate success status 
SS$_BUFFEROVF is returned in the I/O status block. In such cases, 
the message is truncated to fit the buffer. The driver does not provide 
a means for recovering the deleted portion of the message. 


The following function modifier can be specified with a read request: 


¢ IO0$M_NOW—Complete the I/O operation immediately with no wait 
for a write request from another process 


Figure 7-3 illustrates the read mailbox functions. In this figure, process 
A reads a mailbox message written by process B. As the figure indicates, 
a mailbox read request requires a corresponding mailbox write request 
(except in the case of an error). The requests can be made in any sequence; 
the read request can either precede or follow the write request. 


If process A issues a read request before process B issues a write request, 
one of two events can occur. If process A did not specify the function 
modifier IO$M_NOW, process A’s request is queued before process B issues 
the write request. When this request occurs, the data is transferred from 
process B, through the system buffers, to process A to complete the I/O 
operation. 


However, if process A did specify the IO$M_NOW function modifier, the 
read operation is completed immediately. That is, process A’s request 
is not queued until process B issues the write request, and no data is 
transferred from process B to process A. In this case, the I/O status 
returned to process A is SS$_ENDOFFILE. 


If process B sends a message (with no function modifier; see Section 7.3.2) 
before process A issues a read request (with or without a function 
modifier), process A finds a message in the mailbox. The data is 
transferred and the I/O operation is completed immediately. 


To issue the read request, process A can specify any of the read function 
codes; all perform the same operation. 


Write mailbox functions are used to transfer data from a process to a 
mailbox. The VMS operating system provides the following mailbox 
function codes: 


¢ 10$_WRITEVBLK—Write virtual block 
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Figure 7-3 Read Mailbox 
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¢ JO$ WRITELBLK—Write logical block 
e JO$_WRITEPBLK—Write physical block 


These function codes take the following device- or function-dependent 
arguments: 


¢ P1—tThe starting virtual address of the buffer that contains the 
message being written. If P2 specifies a zero-length buffer, P1 is 
ignored. 


e p2—tThe size of the buffer in bytes (limited by the maximum message 
size for the mailbox). A zero-length buffer produces a zero-length 
message to be read by the mailbox reader. 


The following function modifiers can be specified with a write request: 


¢ IO$M_NOW—Complete the I/O operation immediately with no wait 
for another process to read the mailbox message 


¢ IO$M_NORSWAIT—If the mailbox is full, the I/O operation fails with 
a status return of SS$_MBFULL rather than placing the process in 
resource wait mode 


Figure 7-4 illustrates the write mailbox function. In this figure, process A 
writes a message to be read by process B. As in the read request example, 
a mailbox write request requires a corresponding mailbox read request 
(unless an error occurs), and the requests can be made in any sequence. 
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If process A issues a write request before process B issues a read request, 
one of two events can occur. If process A did not specify the function 
modifier IO$M_NOW, process A’s write request is queued before process B 
issues a read request. When this request occurs, the data is transferred 
from process A to process B to complete the I/O operation. 


However, if process A did specify the IO$M_NOW function modifier, the 
write operation is completed immediately. The data is available to process 
B and is transferred when process B issues a read request. 


If process B issues a read request (with no function modifier) before 
process A issues a write request (with or without the function modifier), 
process A finds a request in the mailbox. The data is transferred and the 
I/O operation is completed immediately. 


To issue the write request, process A can specify any of the write function 
codes; all perform the same operation. 


Figure 7-4 Write Mailbox 
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7.3.3 Write End-of-File Message 


Write end-of-file message functions are used to insert a special message 
in the mailbox. The process that reads the end-of-file message is returned 
the status code SS$_ENDOFFILE in the J/O status block. No data is 
transferred. This function takes no arguments. The VMS operating 
system provides the following function code: 


¢ I0$_WRITEOF—Write end-of-file message 


The following function modifier can be specified with a write end-of-file 
request: 


¢ IO$M_NOW—Complete the I/O operation immediately 


7.3.4 Set Attention AST 


Set attention AST functions are used to specify that an AST be delivered 
to the requesting process when a cooperating process places an unsolicited 
read or write request in a designated mailbox. If a message exists in the 
mailbox when a request to enable a write attention AST is issued, the 
AST routine is activated immediately. If no message exists, the AST is 
delivered when a read or write message arrives. Thus the requesting 
process need not repeatedly check the mailbox status. You must have 
both logical I/O and read access to the mailbox prior to performing a set 
attention AST function. 


The VMS operating system provides the following function codes: 
¢ IO$_SETMODE!IO$M_READATTN—Read attention AST 
¢ IO0$_SETMODE!IO$M_WRTATTN—Write attention AST 


These function codes take the following device- or function-dependent 
arguments: 


e P1—AST address (request notification is disabled if the address is 0) 


e P2—AST parameter returned in the argument list when the AST 
service routine is called 


e P8—Access mode to deliver AST; maximized with requester’s mode 


These functions are enabled only once; they must be explicitly reenabled 
after the AST has been delivered if you desire notification of the next 
unsolicited request. Both types of enable functions, and more than one of 
each type, can be set at the same time. The number of enable functions is 
limited only by the AST quota for the process. 


Figure 7—5 illustrates the write attention AST function. In this figure, 
an AST is set to notify process A when process B sends an unsolicited 
message. 


Process A uses the IO$_SETMODE!IO$M_WRTATTN function to request 
an AST. When process B sends a message to the mailbox, the AST is 
delivered to process A. Process A responds to the AST by issuing a read 
request to the mailbox. The function modifier IO$M_NOW is included 
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in the read request. The data is then transferred to complete the I/O 
operation. 


If several requesting processes have set ASTs for unsolicited messages 

at the same mailbox, all ASTs are delivered when the first unsolicited 
message is placed in the mailbox. However, only the first process to 
respond to the AST with a read request receives the data. Thus, when the 
next process to respond to an AST issues a read request to the mailbox, it 
might find the mailbox empty. If this request does not include the function 
modifier IO$M_NOW, it is queued before the next message arrives in the 
mailbox. 


Figure 7-5 Write Attention AST (Read Unsolicited Data) 
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Figure 7-6 illustrates the read attention AST function. In this figure, an 
AST is set to notify process A when process B issues a read request for 
which no message is available. 


Process A uses the IO$_SETMODE!IO$M_READATTN function to specify 
an AST. When process B issues a read request to the mailbox, the AST 
is delivered to process A. Process A responds to the AST by sending a 
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message to the mailbox. The data is then transferred to complete the 1/O 
operation. 


If several requesting processes set ASTs for read requests for the same 
mailbox, all ASTs are delivered when the first read request is placed in the 
mailbox. Only the first process to respond with a write request is able to 
transfer data to process B. 


Figure 7-6 Read Attention AST 
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Set Protection 


Set protection functions allow the user to set volume protection on a 
mailbox (see Section 7.1.4). The requester must either be the owner of the 
mailbox or have BYPASS privilege. The VMS operating system provides 
the following function code: 


¢ I0$ SETMODE!IO$M_SETPROT—Set protection 


7-11 


Mailbox Driver 
7.3 Mailbox Function Codes 


This function code takes the following device- or function-dependent 
argument: 


e P2—A volume protection mask 


The protection mask specified by P2 is a 16-bit mask with four bits for 
each class of owner: SYSTEM, OWNER, GROUP, and WORLD, as shown 


in Figure Figure 7—7. 
Figure 7-7 Protection Mask 
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Only logical I/O, read, and write functions have meaning for mailboxes. A 
clear (0) bit implies that access is allowed. If P2 is 0 or unspecified, the 
mask is set to allow all read, write, and logical operations. 


The I/O status block for the set protection function (see Figure 7-10) 
returns SS$_NORMAL in the first word if the request was successful. If 
the request was not successful, the $QIO system service returns SS$_ 
NOPRIV and both longwords of the I/O status block are returned as zeros. 


7.4 I/O Status Block 


The I/O status blocks (IOSB) for mailbox read, write, and set protection 
QIO functions are shown in Figures 7-8, 7-9, and 7-10. 


Appendix A lists the I/O status returns for these functions. In addition to 
these returns, the system services status returns SS$_ACCVIO, 
SS$_INSFMEM, SS$_MBFULL, SS$_MBTOOSML, and SS$_NOPRIV can 
be returned in RO. (The VMS System Messages and Recovery Procedures 
Reference Manual provides explanations and suggested user actions for 
both types of returns.) 
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Figure 7-8 IOSB Contents - Read Function 
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Figure 7-9 IOSB Contents - Write Function 
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Figure 7-10 lIOSB Contents - Set Protection Function 
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Mailbox Driver Programming Example 


The following program (Example 7-1) creates a mailbox and puts mail 
into it; no matching read is pending on the mailbox. First, the program 
illustrates that if the function modifier IO$M_NOW is not used when mail 
is deposited, the write function waits until a read operation is performed. 
In this case, IO$M_NOW is specified and the program continues after the 
mail is left in the mailbox. 


Next, the mailbox is read. If there is no mail in the mailbox, the program 
waits because IO$M_NOW is not specified. IO$M_NOW should be 
specified if there is any doubt about the availability of data in the mailbox, 
and it is important for the program not to wait. 


It is up to the user to coordinate the data that goes into and out of 
mailboxes. In this example the process reads its own message. Normally, 
two mailboxes are used for interprocess communication: one for sending 
data from process A to process B, and one for sending data from process 
B to process A. If a program is arranged in this manner, there is no 
possibility of a process reading its own message. 


Example 7-1 Mailbox Driver Program Example 


; KREKKKKKRKKKKKKKKKKKKKEKRKEKKK RE KKRKKRKKKKKE RK KREKKEKKKKKKKKEKRKEKRKEKKEKKEKRKEKKKKKEKE 


-TITLE MAILBOX DRIVER PROGRAM EXAMPLE 
-IDENT /01/ 


; Define necessary symbols. 
SIODEF ;Define I/O function codes 


; Allocate storage for necessary data structures. 


+ Allocate output device name string and descriptor. 


DEVICE_DESCR: 


. LONG 20$-10$ ;Length of name string 

. LONG 10$ ;Address of name string 
108: -ASCII /SYSSOUTPUT/ ;Name string of output device 
208: ;Reference label 


? 
; Allocate space to store assigned channel number. 
DEVICE CHANNEL: ; 
- BLKW 1 7;Channel number 
; Allocate mailbox name string and descriptor. 


e 
’ 


(continued on next page) 
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Example 7-1 (Cont.) Mailbox Driver Program Example 





MAILBOX_NAME: 
.LONG ENDBOX-NAMEBOX 
.LONG NAMEBOX 
NAMEBOX: .ASCII /146 MAIN ST/ 
ENDBOX: 


° 
’ 


;Length of name string 
;Address of name string 
;Name string 

;Reference label 


; Allocate space to store assigned channel number. 


. 
7 


MAILBOX CHANNEL: 
. BLKW 1 


. 
, 


. 
, 


;Channel number 


; Allocate space to store the outgoing and incoming messages. 


IN_BOX_BUFFER: 
.BLKB 40 
IN_LENGTH=.-IN_BOX BUFFER 


OUT_BOX_BUFFER: 
.ASCII /SHEEP ARE VERY DIM/ 
OUT_LENGTH=.-OUT_BOX_BUFFER 


° 
, 


;Allocate 40 bytes for 
;received message 
;Define input buffer length 


;Message to send 
7;Define length of message to 
;send 


; Finally, allocate space for the I/O status quadword. 


° 
’ 


STATUS: 
- QUAD 1 


Ne Ne 


=e 


; Start Program 


° 
7 


;I/O status quadword 


KRKEKKEKKKKKKKRKKKKKRKKKKKKKKK KK KKK KKK KK KKK KKKKKKKKEKEKKKE KK KEKKKKKKEKKKKEKEKER 


RKKKEKKEKKEKEKKKKEKEKKEKRKEKRKK KKK KK KEKE KEKE KKK KKK KKEKKE KKK KEKE KKKEKEKKKKKKKKKEKKEK 


; The program first creates a mailbox and assigns a channel to the 


7 process output device. 


Then a message is placed in the mailbox and 
; a message is received from the mailbox (the same message). 


Finally, 


; the program prints the contents of the mailbox on the process output 


3; device. 





(continued on next page) 
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Example 7-1 (Cont.) Mailbox Driver Program Example 


START: 


av 


, 


se 


- WORD 0 


;Entry mask 


SCREMBX_S CHAN=MAILBOX_CHANNEL,- ;Channel is the mailbox 


PROMSK=#*X0000,- 
BUFQUO=#*X0060, - 
LOGNAM=MATLBOX_NAME, — 
MAXMSG=#*X0060 


CMPW #SS$_NORMAL, RO 

BSBW ERROR_CHECK 

SASSIGN_S - 
DEVNAM=DEVICE_DESCR, — 
CHAN=DEVICE_CHANNEL 

CMPW #SS$_NORMAL, RO 

BSBW ERROR_CHECK 


;No protection 

;Buffer quota is hex 60 
;Logical name descriptor 
;Maximum message is hex 60 
;Successful mailbox creation? 
7Find out 

;Assign channel 

;Device descriptor 

; Channel 

;Successful channel assign? 
;Find out 


The program now writes to the mailbox using a write request that 
includes the function modifier IO$M_NOW so that it need not wait for 
a read request to the mailbox before continuing to the next step in 


the program. 


SQIOW_S FUNC=#I0$_WRITEVBLK!IOSM_NOW,- ;Write message NOW 


CHAN=MAILBOX_CHANNEL, ~ 
P1=OUT_BOX_ BUFFER, - 
P2=#0UT_LENGTH 

#SS$ NORMAL, RO 
ERROR_CHECK 


CMPW 
BSBW 


Read the mailbox. 


SQTOW_S FUNC=#I0$_READVBLK, - 
CHAN=MAILBOX_CHANNEL, ~ 
IOSB=STATUS, - 
P1=IN_BOX_BUFFER, - 
P2=#IN LENGTH 

#SS$_ NORMAL, RO 
ERROR_CHECK 


CMPW 
BSBW 


;to the mailbox channel 
;Write buffer 

;Buffer length 

;Successful write request? 
;Find out 


;Read the message 

sin the mailbox channel 
;Define status block to 
;receive message length 
7;Read buffer 

;Buffer length 
;Successful read request? 
;Find out 


The program now determines how much mail is in the mailbox (this 


information is in STATUS+2) 
the process output device. 


MOVZWL 
$QIOW_S 


STATUS+2, R2 
FUNC=#I0$ WRITEVBLK, - 
CHAN=DEVICE_CHANNEL, - 
P1=IN BOX BUFFER, ~ 
P2=R2,- 

P4=#32 


and then prints the mailbox message on 


7Byte count into R2 

;Write function to the 
youtput device channel 
;Address of buffer to write 
;How much to write 
;Carriage control 
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Example 7-1 (Cont.) Mailbox Driver Program Example 





; Finally, deassign the channel and exit. 
EXIT: SDASSGN_S CHAN=DEVICE CHANNEL ;Deassign channel 
RET 7;Return 


; This is the error checking part of the program. Normally, some kind 
; of error recovery would be attempted at this point if an error was 
; detected. However, this example program simply exits. 


ERROR_CHECK: 


° 
7 


BNEQ EXIT ;System service failure, exit 
RSB ;Otherwise, return 
- END START 
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This chapter describes the use of the VMS terminal driver (TTDRIVER) 
and the LAT port driver (LTDRIVER). The terminal driver supports 
the asynchronous, serial line multiplexers listed in Table 8-1. The 
terminal driver also supports the console terminal. The LAT port driver 
accommodates I/O requests from application programs, for example to 
make connections to remote devices, such as a printer, on a server (see 
Section 8.4.4). 





Supported Terminal Devices 


In addition to the multiplexers listed in Table 8-1, the terminal driver 
supports serial line interfaces that are included as part of all VAX 
processors. At least one such interface is always provided and is used 

to attach the system console terminal. This interface does not allow the 
setting of multiple terminal speeds, parity, or any maintenance functions, 
with the exception of the interface included with the VAX 8200 processor. 
The terminal devices supported by the VMS operating system for this 
interface are included in Table 8-1. 


The remote command terminal, used by the DCL command SET HOST, 
also makes use of the features listed in Section 8.2. 


Table 8-1 Supported Terminal Devices 


Terminal 
interface 


CXY08 

CXA16 

CXBi6 

DZQ11 
DZQ11-CR 
MicroVAX 2000 
MicroVAX 3100 
DZV11 

DHQ11 

DHU11 

DHV11 

DMB32 


No. of eel! a) Split International 
Lines Silo DMA Speed Bus Modem Control 
8 Yes' Yes Yes Q-bus Full 

16 Yes' Yes Yes Q-bus No 

16 Yes' Yes Yes Q-bus No 

4 No No Yes Q-bus No 

4 No No Yes Q-bus No 

4 No No Yes None No 

4 No No Yes None No 

4 No No No Q-bus No 

8 Yes' Yes Yes Q-bus Full 

16 Yes Yes Yes UNIBUS Full 

8 No Yes Yes Q-bus Full 

8 No Yes Yes VAXBI bus Full 


‘Depends on whether the DHV or DHU mode is selected when the board is installed 


(continued on next page) 
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Table 8-1 (Cont.) Supported Terminal Devices 


Terminal No. of 
Interface Lines 
DHB32 16 
DSH32 8 
DMF32 8 
DMZ32 24 
DZ11 8/16 
DZ32 8 
LAT : 
VAX 8200 4 
serial lines 

VAXstation 3100 4 


2Lines 0 and 1. 
3Server dependent. 


otal Split International 
Silo DMA _ Speed Bus Modem Control 
No Yes Yes VAXBI bus Full 
Yes No Yes MicroVAX 2000, No 
MicroVAX 3100 
Yes Yes? Yes? UNIBUS Yes 
Yes Yes Yes UNIBUS Full 
No No No UNIBUS No 
No No Limited UNIBUS No 
No Yes 3° N/A ; 
No No No‘ None No 
No No Yes None No 


4The VMS operating system always supports the first serial line as a console interface. The first serial line and the remaining 
three serial lines are also supported as user terminal interfaces at a maximum speed of 1200 baud in configurations that can 
include a LAT terminal interface but do not include other terminal interfaces. 





Terminal Driver Features 


The VMS terminal driver provides the following features: 
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Input processing 

— Command line editing and command recall 

— Control characters and special keys 

— Input character validation (read verify) 

— American National Standard (ANSD escape sequence detection 
— Type-ahead feature 

— Specifiable or default input terminators 

— Special operating modes, such as NOECHO and PASTHRU 
Output processing 

— Efficiency 

— Limited full-duplex operation 

— Formatted or unformatted output 

Dial-up support 

— Modem control 

— Hangup on logging out 


— Preservation of process across hangups 
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¢ Miscellaneous 
— Terminal/mailbox interaction 
— Autobaud detection 


— Out-of-band control character handling 


8.2.1. Input Processing 


The VMS terminal driver defines many terminal characteristics and read 
function modifiers, which provide a wide range of options to an application 
program. These options allow multiple levels of control over the terminal 
driver’s input process, ranging from the default of command line editing 
that provides a highly flexible user interface, to the PASTHRU mode, 
which inhibits input process interpretation of data. 


8.2.1.1 Command Line Editing and Command Recall 
The terminal driver input process defines a bounded set of line editing 
functions. These functions are available through control keys on all 
keyboards, and through some special keys on certain keyboards as well. 
Cursor movement is provided in single-character increments (left arrow 
or CTRL/D, right arrow or CTRL/F), or in multicharacter increments, to 
beginning of the line (CTRL/H), or end of the line (CTRL/E). The terminal 
driver supports both insert character and overstrike character modes. 
The insert/overstrike mode is the terminal’s default characteristic! at 
the beginning of a read operation, but it can be changed dynamically 
with the toggle insert/overstrike key (CTRL/A). Deletion of characters is 
supported in both word (CTRL/J or line feed), and to the beginning of the 
line (CTRL/V) increments. 


When you use the terminal driver’s editing functions, the following 
restrictions result: 


e The cursor cannot be moved to a previous line after a line wrap. 


¢ A ccharacter cannot be inserted if the insertion would force a line wrap 
or if a tab follows the current cursor position. 


¢ A word cannot be deleted at the beginning of a line after a line wrap. 


¢ The line editing function cannot be assigned to other keys. 


Command recall, initiated by CTRL/B or the up arrow, returns the last 
line entered to the command line buffer. At this point, the line can be 
edited or reentered by pressing the Return key. DCL extends command 
recall to the last 20 commands by using the TRM$M_TM_NORECALL 
modifier to disable the terminal driver’s recall mechanism. 


Any control key that is not defined by line editing is ignored. For 
application programs that require control key input but do not perform 
QIO functions with special read modifiers, the DCL command SET 
TERMINAL/NOLINE_EDIT restores most of the terminal driver behavior 
described under VMS Versions 3.0 through 3.7. 


' It is suggested that new users specify overstrike mode. 
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8.2.1.2 Control Characters and Special Keys 
A control character is a character that controls action at the terminal 
rather than passing data to a process. An ASCII control character has 
a code between 0 and 31, and 127 (hexadecimal 0 through 1F, and 7F); 
that is, all normal control characters plus DELETE. (Table B-1 lists the 
numeric values for all control characters.) 


Some control characters are entered at the terminal by simultaneously 
pressing the CTRL key and a character key, such as CTRL/x. Table 8-2 
lists the VMS terminal control characters. Control character echo strings 
(CTRL/C, CTRL/Y, CTRL/O, and CTRL/Z) can be changed on a systemwide 
basis (see the VMS System Generation Utility Manual). Special keys, such 
as RETURN, LINE FEED, and ESCAPE, are entered by pressing a single 
key. 


Several of the control characters do not function as described if the SET 
TERMINAL/LINE_EDIT DCL command is not specified. See the VMS 
DCL Dictionary for information on line editing function keys and the SET 
TERMINAL command. 


Table 8-2 Terminal Control Characters 


Control Character Meaning 
Cancel Gains the attention of the enabling process if the user program has enabled a 
(CTRL/C - F6') CTRL/C AST. If a CTRL/C AST is not enabled, CTRL/C is converted to CTRL/Y 


(see Section 8.4.3.2). 


The terminal performs a carriage-return/line-feed combination (carriage return followed 
by a line feed), echoes CANCEL, and performs another carriage-return/line-feed 
combination. If the terminal has the ReGIS characteristic or if CTRL/Y is pressed, the 
cancel ReGIS escape sequence is sent. 


Additional consequences of CTRL/C are as follows: 


¢« The type-ahead buffer is emptied. 
¢ CTRL/S and CTRL/ are reset. 


¢ All queued and in-progress write operations and all in-progress read operations 
are successfully completed. The status return is SS$_CONTROLC, or 
SS$_CONTROLY if CTRL/C is converted to CTRL/Y. 


Delete character Removes the last character entered from the input stream. 

(DELETE) 
DELETE (decimal 127 or hexadecimal 7F) is ignored if there are currently no input 
characters. Hardcopy terminals echo the deleted character enclosed in backslashes. 
For example, if the character z is deleted, \z\ is echoed (the second backslash is 
echoed after the next non-DELETE character is entered). Terminals that have the 
TT$M_SCOPE characteristic echo DELETE by removing the character. 


1F6 on the LK201 is Interrupt/Cancel. 


(continued on next page) 
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Table 8-2 (Cont.) Terminal Control Characters 


Control Character 


Delete line 
(CTRL/U) 


Delete word 
(CTRL/J or F13) 
(Line feed) 


Discard output 
(CTRL/O) 


End of line 
(CTRL/E) 

Exit 

(CTRL/Z or F10) 


Interrupt 
(CTRL/Y) 


Move cursor left 
(CTRL/D <) 


Move cursor right 
(CTRL/F —) 


Meaning 


Purges current input data. When CTRL/U is entered before the end of a read 
operation, the current input line is deleted. (In the case of a line-wrap, CTRL/U 
deletes only a line at a time.) If line editing is enabled (SET TERMINAL/LINE_EDIT 
is specified), the data from the beginning of the line to the current cursor position is 
deleted. 


Delete word before cursor. Word terminators are all control characters, space, comma, 
dash, period, and! "#$&/’()+@[\]4{ | ~/:;<>=? (see Appendix B). 


Discards output. Action is immediate. All output is discarded until the next read 
operation, the next write operation with a IO$M_CANCTRLO modifier, or the receipt of 
the next CTRL/O. The terminal echoes OUTPUT OFF. The current write operation (if 
any) and write operations performed while CTRL/O is in effect are completed with a 
status return of SS$_CONTROLO. 


A second CTRL/O, which reenables output, echoes OUTPUT ON. CTRL/C, CTRL, 
and CTRL/T cancel CTRL/O. 


Moves the cursor to the end of the line. 


Echoes EXIT when CTRL/Z is entered as a read terminator. By convention, CTRL/Z 
constitutes end-of-file. 


CTRL/ is a special interrupt or attention character that is used to invoke the command 
interpreter for a logged-in process. CTRL/Y can be enabled with an IO$M_CTRLYAST 
function modifier to an 1O$ SETCHAR or 1O$_SETMODE function code. The 
command interpreter’s CTRL/Y AST handler always takes precedence over a user 
program’s CTRL/Y AST handler. 


Entering CTRL/Y results in an AST to an enabled process to signify that the user 
entered CTRL/Y from the terminal. The terminal performs a carriage-return/line-feed 
combination, echoes INTERRUPT, and performs another carriage-return/line-feed 
combination if the AST and echo are enabled. CTRL/Y is ignored (and not echoed) if 
the process is not enabled for the AST. 


Additional consequences of CTRL/Y are as follows: 


¢ The type-ahead buffer is flushed. 
* CTRL/S and CTRUO are reset. 


¢ All queued and in-progress write operations and all in-progress read operations 
are successfully completed with a 0 transfer count. The status return is 
SS$_CONTROLY. 


* The cancel ReGIS escape sequence is sent. 


Moves the cursor one position to the left. 


Moves the cursor one position to the right. 


(continued on next page) 
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Table 8—2 (Cont.) Terminal Control Characters 


Control Character 


Move cursor to 
beginning of line 
(CTRU/H or F12) 
(Back space) 


Purge type ahead 
(CTRL/X) 


Recall 
(CTRL/B or 
up arrow) 


Redisplay input 
(CTRL/R) 


Restart output 
(CTRL/Q) 


RET 
(RETURN) 


Stop output 
(CTRL/S) 


TAB 
(CTRL) 


Status 
(CTRL/T) 


Toggle 
insert/overstrike 
(CTRL/A or F14) 


8.2.1.3 
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Meaning 


Moves the cursor to the beginning of the line. 


Purges the type-ahead buffer and performs a CTRL/U operation. Action is immediate. 
If a read operation is in progress, the operation is equivalent to CTRL/U. 


Recalls last command entered. DCL extends recall to several commands. 


Redisplays current input. When CTRL/R is entered during a read operation, a carriage- 
return/line-feed combination is echoed on the terminal, and the current contents of the 
input buffer are displayed. If the current operation is a read with prompt (lO$_ 
READPROMPT) operation, the current prompt string is also displayed. CTRL/R has © 
no effect if the characteristic TT$M_NOECHO is set. 


Controls data flow; used by terminals and the driver. Restarts data flow to and from a 
terminal if previously stopped by CTRL/S. The action occurs immediately with no echo. 
CTRL/Q is also used to solicit read operations. 


CTRL/Q is meaningless if the line does not have the characteristic TT$M_TTSYNC, 
the characteristic TT$M_READSYNG, or is not currently stopped by CTRL/S. 


If used during a read (input) operation, RET echoes a carriage-return/line-feed 
combination. All carriage returns are filled on terminals with TT$M_CRFILL specified. 


Controls data flow; used by both terminals and the terminal driver. CTRL/S stops all 
data flow; the action occurs immediately with no echo. CTRL/S is also used to stop 
read operations. CTRL/S is meaningful only if the terminal has either the 
TT$M_TTSYNC characteristic or the TT$M_READSYNC characteristic. 


Tabs horizontally. Advances to the next tab stop on terminals with the characteristic 
TT$M_MECHTAB, but the terminal driver assumes tab stops on MODULO 8 (multiples 
of 8) cursor positions. On terminals without this characteristic, enough spaces are 
output to move the cursor to the next MODULO 8 position. 


Displays the current time. CTRL/T also displays the current node and user name, the 
name of the image that is running, and information about system resources that have 
been used during the current terminal session. 


Changes current edit mode from insert to overstrike, or from overstrike to insert. The 
default mode (as set with SET TERMINAL/LINE_EDIT) is reset at the beginning of 
each line. 


Read Verify 


The read verify instructions provided by the terminal driver allow 
validation of data as each character is entered. Invalid characters are 

not echoed and terminate the operation. The terminal driver does not 
support full function field processing. Large data entry applications should 
use one of the DECforms, VAX FMS, or VAX TDMS layered products, 
which support the entire data entry environment. Section 8.4.1.4 describes 
the supported primitives. 
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8.2.1.4 Escape and Control Sequences 
Escape and control sequences provide additional terminal control not 
furnished by the control characters and special keys (see Section 8.2.1.2). 
Escape sequences are strings of two or more characters, beginning with 
the escape character (decimal 27 or hexadecimal 1B), which indicate 
that control information follows. Many terminals send and respond to 
such escape sequences to request special character sets or to indicate the 
position of a cursor. 


The set mode characteristic TT$M_ESCAPE (see Table 8—5) is used to 
specify that VMS terminal lines can generate valid escape sequences. 
Also, the read function modifier IO$M_ESCAPE allows any read operation 
to terminate on an escape sequence regardless of whether TT$M_ESCAPE 
is set. If either TT$M_ESCAPE or IO$M_ESCAPE is set, the terminal 
driver verifies the syntax of the escape sequences. The sequence is always 
considered a read function terminator and is returned in the read buffer; 
a read buffer can contain other characters that are not part of an escape 
sequence, but a complete escape sequence always terminates a read 
operation. The return information in the read buffer and the I/O status 
block includes the position and size of the terminating escape sequence in 
the data record (see Section 8.5). 


Any escape sequence received from a terminal is checked for correct 
syntax. If the syntax is not correct, SS$_BADESCAPE is returned as the 
status of the I/O. If the escape sequence does not fit in the user buffer, 
SS$_PARTESCAPE is returned. If SS$¢_PARTESCAPE is returned, the 
application program must issue enough single-character read requests, 
without timeout, to read the remaining characters in the escape sequence, 
while parsing the syntax of the rest of the escape sequence. Use of the 
TRM$_ESCTRMOVR item code prevents SS$_PARTESCAPE errors. No 
syntax integrity is guaranteed across read operations. Escape sequences 
are never echoed. Valid escape sequences take any of the following forms 
(hexadecimal notation): 


ESC <int>...<int> <fin> (7-bit environment) 
CSI <int>...<int> <fin> (8-bit environment) 
The keywords in the escape sequences indicate the following: 


ESC The ESC key, a byte (character) of 1B. This character introduces the escape 
sequence in a 7-bit environment. 


CSI The Control Sequence Introducer, a byte (character) of 9B. This character 
introduces the escape sequence in a 8-bit environment. 
<int> An “intermediate character” in the range of 20 to 2F. This range includes 


the space character and 15 punctuation marks. An escape sequence can 
contain any number of intermediate characters, or none. 


<fin> A “final character” in the range of 30 to 7E. This range includes uppercase 
and lowercase letters, numbers, and 13 punctuation marks. 


Three additional escape sequence forms are as follows: 


ESC <;> <20-2F>...<30-7E> 
ESC <?> <20-2F>...<30-7E> 
ESC <O> <20-2F>...<40-7E> 
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Control sequences, as defined by the ANSI standard, are escape sequences 
that include control parameters. Control sequences have the following 
format: 


ESC [ <par>...<par> <int>...<int> <fin> (7-bit environment) 
CSI <par>...<par> <int>...<int> <fin> (8-bit environment) 
The keywords in the escape sequences indicate the following: 


ESC The ESC key, a byte (character) of 1B. 
[ ; A control sequence, a byte (character) of 5B. 


CSI The Control Sequence Introducer, a byte (character) of 9B. 
<par> A parameter specifier in the range of 30 to 3F. 
<int> An “intermediate character” in the range of 20 to 2F. 


<fin> A “final character” in the range of 40 to 7E. 


For example, the position cursor control sequence is ESC [ Pl; Pc H. Plis 
the desired line position and Pc is the desired column position. 


The user guides for the various terminals list valid escape and control 
sequences. For example, the VT100 User Guide lists the escape and 
control sequences for VT100 terminals. 


Section 8.2.1.2 describes control character functions during escape 
sequences. 


Table B-2 lists the valid ANSI and DIGITAL-private escape sequences 

for terminals that have the TT2$M_ANSICRT, TT2$M_DECCRT, 
TT2$M_DECCRT2, TT2$M_AVO, TT2$M_EDIT, and TT2$M_BLOCK 
characteristics (see Table 8-6). Table B-2 also lists assumed and selectable 
ANSI modes and selectable DIGITAL-private modes. Only the names of 
the escape sequences and modes are listed (for more information see the 
specific user guide for any of the various terminals). Unless otherwise 
noted, the operation of escape sequences and modes is identical to the 
particular terminals that implement these features. 


8.2.1.5 Type-Ahead Feature 
Input (data received) from a VMS terminal is always independent of 
concurrent output (data sent) to a terminal. This feature is called type- 
ahead. Type-ahead is allowed on all terminals, unless explicitly disabled 
by the set mode characteristic, inhibit type-ahead (TT$M_NOTYPEAHD; 
see Table 8-5 and Section 8.4.3). 


Data entered at the terminal is retained in the type-ahead buffer until 
the user program issues an I/O request for a read operation. At that time, 
the data is transferred to the program buffer and echoed at the terminal 
where it was typed. 


Deferring the echo until the read operation is active allows the user 
process to specify function code modifiers that modify the read operation. 
These modifiers can include, for example, noecho (IO$M_NOECHO) 

and convert lowercase characters to uppercase (IO$M_CVTLOW) (see 
Table 8-7). 


If a read operation is already in progress when the data is typed at the 
terminal, the data transfer and echo are immediate. 
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The action of the driver when the type-ahead buffer fills depends on the set 
mode characteristic TT$M _HOSTSYNC (see Table 8-5 and Section 8.4.3). 
If TT$M_HOSTSYNC is not set, CTRL/G (BELL) is returned to inform 
you that the type-ahead buffer is full. If characters are entered when the 
type-ahead buffer is full, the next read operation completes with a status 
return of SS$¢_DATAOVERUN. If TT$M_HOSTSYNC is set, the driver 
stops input by sending a CTRL/S and the terminal responds by sending no 
more characters. These warning operations begin eight characters before 
the type-ahead buffer fills unless the TT2$M_ALTYPEAHD characteristic 
is set. In that case, the system generation parameter TTY_ALTALARM 

is used. The driver sends a CTRL/Q to restart transmission when the 
type-ahead buffer empties completely. 


The type-ahead buffer length is variable, with possible values in the 
range from 0 through 32,767. The length can be set on a systemwide 
basis through use of the system generation parameter TTY_TYPAHDSZ. 
Terminal lines that do a large amount of bulk input should use the 
characteristic TT2$M_ALTYPEAHD, which allows the use of a larger 
type-ahead buffer specified by the system generation parameters TTY_ 
ALTYPAHD and TTY_ALTALARM. (TTY_ALTYPAHD specifies the total 
size of the alternate type-ahead buffer; TTY_ALTALARM specifies the 
threshold at which a CTRLU/S is sent.) 


Certain input-intensive applications, such as block mode input terminals, 
can take advantage of an optimization in the driver. If a terminal has the 
characteristic TT2$M_PASTHRU and the read function modifier 
IO$M_NOECHO is specified, data is placed directly into the read buffer 
and thereby eliminates the overhead for moving the data from the type- 
ahead buffer. 


8.2.1.6 Line Terminators 
A line terminator is the control sequence that you type at the terminal to 
indicate the end of an input line. Optionally, the application can specify a 
particular line terminator or class of terminators for read operations. 


Terminators are specified by an argument to the QIO request for a read 
operation. By default, they can be any ASCII control character except 
FF, VT, LF, TAB, or BS (see Appendix B). If line editing is enabled, the 
only terminators are CR, CTRL/Z, or an escape sequence. Control keys 
that do not have an editing function are nonfunctioning keys. If included 
in the request, the argument is a user-selected group of characters (see 
Section 8.4.1.2). 


All characters are 7-bit ASCII characters unless data is input on an 
8-bit terminal (see Section 8.4.1). The characteristic TT$M_EIGHTBIT 
determines whether a terminal uses the 7-bit or 8-bit character set; 
see Table 8-5. All input characters (except some special keys; see 
Section 8.2.1.2) are tested against the selected terminators. The input 
is terminated when a match occurs or your input buffer fills. 


The terminal driver notifies the job controller to initiate login when it 
detects a carriage return terminator on a line with no current process 
(provided the line is not a secure server or the type-ahead feature has not 
been disabled). A bell character is sent when the notification occurs. A 
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notification character other than the bell character may be specified by 
setting the system generation parameter TTY_AUTOCHAR. 


8.2.1.7 Special Operating Modes 
The VMS terminal driver supports many special operating modes for 
terminal lines. (Tables 8—5 and 8-6 in Section 8.3 list these modes.) 
All special modes are enabled or disabled by the set mode and set 
characteristics functions (see Section 8.4.3). 


8.2.2 Output Processing 


Output handling is designed to be very efficient in the terminal driver. For 
example, on multiplexers that support both silo and direct memory access 
(DMA) ouput, the driver considers record size to decide dynamically which 
mode will result in the least overhead. The block size specified by the 
system generation parameter TTY_DMASIZE is the minimum size block 
that can be used in a DMA operation. 


8.2.2.1 Duplex Modes 
The VMS terminal driver can execute in either half- or full-duplex 
mode. These modes describe the terminal driver software, specifically 
the ordering algorithms used to service read and write requests, not the 
terminal communication lines. 


In half-duplex mode, all read and write requests are inserted onto one 
queue. The terminal driver removes requests from the head of this queue 
and executes them one at a time; all requests are executed sequentially in 
the order in which they were issued. 


In full-duplex mode, read requests (and all other requests except write 
requests) are inserted onto one queue and write requests onto another. 
The existence of two queues allows the driver to recognize the presence 
of two requests, such as a read request and a write request at the same 
time. However, the driver does not execute the read request and the write 
request simultaneously. When it is ready to service a request, the driver 
decides which request—the read request or the write request—to process 
next. 


In the VMS terminal driver, write requests usually have priority. A write 
request can interrupt a current, but inactive, read request. A read request 
is current when the terminal driver removes that request from the head 
of the read queue. In a read operation, the read request becomes active 
when the first input character is received and echoed. Once a read request 
becomes active, all write requests are queued until the read completes. 
However, during a read operation many write requests can be executed 
before the first input character is entered at the terminal. Terminal 

lines that have the TT$M_NOECHO characteristic, or read functions 

that include the IO$M_NOECHO function modifier, do not inhibit write 
operations in full-duplex mode. 


If a write function specifies the IO$M_BREAKTHRU modifier, the write 
operation is not blocked, even by an active read operation. 
IO$M_BREAKTHRU does not change the order in which write operations 
are queued. 
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When all I/O requests are entered using the Queue I/O Request and Wait 
($QIOW) system service, there can be only one current I/O request at a 
time. In this case, the order in which requests are serviced is the same for 
both half- and full-duplex modes. 


The type-ahead buffer always buffers input data for which there is no 
current read request, in both half- and full-duplex modes. 


8.2.2.2 Formatting of Output 
By default, output data is subject to formatting by the terminal driver. 
This formatting includes actions such as wrapping, tab expansion, 
uppercase, and fallback conversions. Applications that do not require 
formatting of data can write with the IO$M_NOFORMAT modifier and 
thereby reduce overhead. IO$M_NOFORMAT overrides all formatting 
except fallback translation. Setting the PASTHRU mode (TT2$M_ 
PASTHRVU) is equivalent to writing with the noformat modifier. 


Fallback conversions occur regardless of formatting mode. 


8.2.2.3 SET HOST Facility and Output Buffering 
The SET HOST facility emulates the VMS terminal driver in the way it 
writes data to the terminal by stopping the display as soon as the abort 
character is entered. However, the SET HOST facility behaves differently 
from the VMS terminal driver in that it buffers output data from the 
program that is executing. Occasionally, this causes a perception problem 
for the user when the program is aborted with a CTRL/C, CTRL/Y, or an 
out-of-band abort character. The user expects the program to terminate 
and the display to stop immediately. 


CTDRIVER and RTPAD 


When used between two systems running the VMS operating system, the 
SET HOST facility consists of two components: RTPAD on the local VAX 
node and CTDRIVER on the remote VAX node. Both components buffer 
output data to enhance performance when using wide area networks. 
CTDRIVER performs the initial buffering, queues the buffers for network 
transfer, and returns a successful write status. The user should note that 
the local terminal display reflects the output of the executing program 
after the data has been buffered and transferred over the network—not as 
the output buffers are filled on the remote node. 


The delay between execution of an application and the display of its 
output can lead to several anomalies in the effects of CTRL/C, CTRL/Y, 
and out-of-band abort characters. 


Output Line Not in Sequence Following an Abort Character 


After you enter an abort character (CTRL/C, CTRL/Y or an out-of-band 
abort character) that causes the input or output to be aborted, it is possible 
to receive an additional line of output. This occurs when the application 
program calls $QIO (either directly or indirectly through VMS RMS or 
language support routines) to output data to a buffer at the same time the 
abort character is entered. 
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Note: 


Note: 


When CTDRIVER receives the abort character (CTRL/C, CTRL/Y, or an 
out-of-band abort character) from the network, it flushes the current 
output buffers and aborts any pending read operations. However, if the 
application program calls $QIO with a write operation when the abort 
character is entered, the $QIO write data is still buffered and then 
displayed. The data may not be the next output in sequence from the 
user’s point of view, since all the previous output buffers in CTDRIVER 
were flushed and the data in them was not displayed. 


When using the VMS terminal driver, the effect of an abort character on 
the display screen is different. The VMS terminal driver does not buffer 
output from the application during program execution. If the application 
program has just called $QIO with a write operation when the abort 
character is entered, then the $QIO write data is displayed. Because all 
write operations are sequential and do not complete until the output is 
actually displayed, the additional line displayed is in sequence. There is 
no break in the data. Normally, the user will not notice that there is an 
additional line. . 


Extra Input Prompt Following an Abort Character 


For connections between systems running the VMS operating system, the 
CTERM protocol allows CTDRIVER to synchronize with RTPAD before 
displaying any more data on the terminal. 


Prior to VMS version 5.2, a control character entered during 
program execution to abort input and output could cause the 
system to display more than one input prompt. 


If the SET HOST facility is used between systems running VMS 
version 5.2 and an earlier version, the extra input prompt is still 
displayed. . 


Processing Abort Characters 


The abort character AST is delivered after the message describing the 
aborted read operation has been received. Thus, the read status should 
be set very shortly after the abort character AST is delivered to the 
application. Note, however, these are still two asynchronous events, and 
the application must still synchronize with the completing read operation. 


Prior to VMS Version 5.2, if an application had a read operation 
pending and had queued a CTRL/C, CTRL/Y, and out-of-band abort 
character AST, it was possible to queue multiple read operations 
unknowingly when the read operation was aborted. 


Captive Command Procedures and CTRL/Y 


CTDRIVER and RTPAD emulate the VMS terminal driver in that the 
current read operation and all pending write operations abort when 
CTRL/Y is entered. However, the pending write operations also include all 
the buffered output that occurred and that would have been output before 
the CTRL/Y was entered but due to the buffering was not. 


8.2.3 


Dial-Up Support 
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The effect of the buffering can be confusing if a CTRL/Y is entered when 
a captive command procedure is executing. During execution of captive 
command procedures, DCL has a CTRL/Y pending. When this AST is 
delivered, DCL only reenables it; no other action is performed. In that 
case, if the program being executed only performs output, it appears 
that the program was aborted by the CTRL/Y. Actually, the program 
completed execution before the CTRL/Y was entered, and the CTRL/Y 
merely discarded all the buffered output. 


The VMS operating system supports modem control (for example, Bell 
103A, Bell 113, or equivalent) for all supported multiplexers in autoanswer, 
full-duplex mode. The terminal driver does not support half-duplex 
operations on modems such as the Bell 202. Also not supported are 
modems that use circuit 108/1 (connect data set to line signal) in place of 
the data terminal ready (DTR) signal. Most U.S. and European modems 
use the data terminal ready signal, which is the signal supported by the 
VMS operating system. 


8.2.3.1 Modem Signal Control 


Note: 


Dial-up lines with the characteristic TT$M_MODEM are monitored 
periodically to detect a change in the modem carrier signals data set 
ready (DSR), calling indicator (RING), or request to send (RTS). The 
system generation parameter TTY_SCANDELTA establishes the dial-up 
monitoring period for multiplexers that do not support modem signal 
transition interrupts (see Table 8-1). 


If a line’s carrier signal is lost, the driver waits two seconds for the 
carrier signal to return. If bit 0 of the system generation parameter TTY_ 
DIALTYPE is set to 1, the driver does not wait. Bit 0 is 0 by default for 
countries with Bell System standards, but that bit should be set to 1 for 
countries with Comite Consultatif Internationale (CCITT) standards. If 
the carrier signal is not detected during this time, the line is hung up. 
The hangup action can signal the owner of the line, through a mailbox 
message, that the line is no longer in use. (No dial-in message is sent; the 
unsolicited character message is sufficient when the first available data 

is received.) The line is not available for a minimum of two seconds after 
the hangup sequence begins. The hangup sequence is not reversible. If 
the line hangs up, all enabled CTRL/Y and out-of-band ASTs are delivered; 
the CTRL/Y AST P2 argument is overwritten with SS$_HANGUP. The I/O 
operation in progress is canceled, and the status value SS$_HANGUP is 
returned in the I/O status block. DCL is responsible for process deletion 
after CTRL/Y is delivered. If the process is suspended, DCL cannot run, 
and therefore deletion cannot occur, until the process is resumed. 


Some systems, such as the VAXstation 3100, provide built-in serial 
lines using 6-pin modular jacks. These lines do not provide the 
minimum required modem signals. Although, the hardware may 
allow a dial-out connection to be established, hangup cannot be 
detected and process deletion will not occur on these lines. 
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For terminals with the TT$M_MODEM characteristic, TT$M_REMOTE 
reflects the state of the carrier signal. TT$M_REMOTE is set when the 
carrier signal changes from off to on, and cleared when the carrier signal 
is lost. 


A line that does not have TT$M_MODEM set does not respond to 
modem signals or set the DTR signal. Modem signals can be set and 
sensed manually through use of the IO$M_MAINT function modifier (see 
Section 8.4.3.3). 


The VMS terminal driver default modem protocol meets the requirements 
of the United States and of European countries. This protocol is capable of 
working in automatic answer mode and can also perform manually dialed 
outgoing calls. The protocol supports the requirements of most known 
international telephone networks. Enhanced modem features are used on 
multiplexers that support them; processor polling is not necessary. The 
protocol also functions in a subset mode for the multiplexers that do not 
support full modem signals (see Table 8-1). 


Table 8-3 lists the control and data signals used in a full modem control 
mode configuration (in a two-way simultaneous, symmetrical transmit 
mode). Figure 8-1 is a flowchart that shows a typical signal sequence for 
a terminal operation in this mode. The flowchart shows the states that the 
modem transition code goes through to detect different types of transitions 
in modem state. These transitions allow the driver to detect loss of lines 
that have been idle for several minutes. Modem states do not affect the 
ability of the system to transmit characters. 


Set mode function modifiers are provided to allow a process to activate or 
deactivate modem control signals (see Section 8.4.3.3). 


Bit 1 of the system generation parameter TTY_DIALTYPE enables 
alternate modem protocol on a systemwide basis. If bit 1 is 0 (the default), 
the RING signal is not used. If bit 1 is 1, the modem protocol delays 
setting the DTR signal until the RING signal is detected. 


Remote terminal connections have a timeout feature for the security of 
dial-up lines. If no channel is assigned to the port within 30 seconds, or a 
port with an assigned channel is not allocated, the DTR signal is dropped. 
Such action prevents an unused terminal from tying up a line. However, 
there are configurations (such as a printer connected to a remote line) 

in which the line should not be dropped even though it is not being used 
interactively. To bypass the 30-second timeout, set the system generation 
parameter TTY_DIALTYPE to 4. (Note that if TTY_DIALTYPE is equal 
to 4, all dial-up lines will skip the timeout waiting for a channel to be 
assigned.) 
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Figure 8-1 Modem Control - Two-Way Simultaneous Operation 
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Table 8-3 Control and Data Signals (Full Modem Mode Configuration) 


Signal 


Transmitted 
data (TxD) 


Received data 
(RxD) 


Request to 
send (RTS) 


Clear to send 
(CTS) 


Data set ready 
(DSR) 


Data channel 
received line 
signal detector 
(CARRIER) 


Data terminal 
ready (DTR) 


Calling 
indicator 
(RING) 


Source 


Computer 


Modem 


Computer 


Modem 


Modem 


Modem 


Computer 


Modem 


MUX" 
All 


All 


Full 


Full 


Full 


All 


All 


All 


Meaning 


The data originated by the computer and transmitted through 
the modem to one or more remote terminals. 


The data generated by the modem in response to telephone 
line signals received from a remote terminal and transferred to 
the computer. 


lf present (ON condition), RTS directs the modem to assume 
the transmit mode. If not present (OFF condition), RTS directs 
the modem to assume the nontransmit mode after all transmit 
data has been transmitted. 


Indicates whether the modem is ready (ON condition) or not 
ready (OFF condition) to transmit data on the telephone line. 


If present (ON condition), DSR indicates that the modem is 
ready to transmit and receive; that is, the modem is connected 
to the line and is ready to exchange further control signals with 
the computer to initiate the exchange of data. 


If DSR is not present (OFF condition), the modem is not ready 
to transmit and receive. If DSR is detected, the VMS operating 
system initiates a 30-second timer. This ensures that the 
phone line will be disconnected if CARRIER is not detected. 


If present (ON condition), CARRIER indicates that the received 
data channel line signal is within appropriate limits, as specified 
by the modem. If not present (OFF condition), the received 
signal is not within appropriate limits. 


If present (ON condition), DTR indicates that the computer 

is ready to operate, prepares the modem to connect to the 
telephone line, and maintains the connection after it has been 
made by other means. DTR can be present whenever the 
computer is ready to transmit or receive data. If DTR is not 
present (OFF condition), the modem disconnects the modem 
from the line. 


Indicates whether a calling signal is being received by the 
modem. Bit 1 of the system generation parameter TTY_ 
DIALTYPE must be set (=1). If RING is detected, the VMS 
operating system initiates a 30-second timer. This ensures 
that the phone line will be disconnected if CARRIER is not 
detected. 





‘Multiplexers (All = any supported controller; Full = DZ32, DMF32, DMB32, DMZ32, DHU11, DHV11, and CXY08) 





8.2.3.2 Hangup on Logging Out 


By default, logging out on a line with modem signals will not break the 
connection. If TT2$M_HANGUP is set, modem signals are dropped when 
the process logs out. If TT2$M_MODHANGUP is set, no privilege is 
required to change the state of TT2$M_HANGUP. By setting 
TT2M_HANGUP, system managers can prevent nonprivileged users who 
are not logged in from tying up a dial-in line. 
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8.2.3.3 Preservation of a Process Across Hangups 
Disconnectable terminals allow a connection to a physical terminal line to 
be broken without losing the job. The following SYSGEN command allows 
terminals to be disconnectable terminals: 


SYSGEN> CONNECT VTAO/NOADAPTER/DRIVER=TTDRIVER 


After this command is entered, a terminal with the TT2$M_DISCONNECT 
characteristic logs in as VTAn:, rather than with the physical terminal 
name. When a terminal is set up in this manner, no input or output 
operations are allowed to the physical device; I/O is automatically 
redirected to the appropriate virtual terminal. 


Following are four ways in which a terminal can become disconnected: 
¢ Modem signals between the host and the terminal are lost. 


e Auser presses the BREAK key on a terminal that has the 
TT2$M_SECURE characteristic. 


e A user issues the DCL command DISCONNECT. 
e¢ A user issues the DCL command CONNECT/CONTINUE. 


After being validated as a user, you can connect to a disconnected process 
in either of the following ways: 


e Allow the login process to make the connection. 
e Issue the DCL command CONNECT. 


8.2.4 Terminal/Mailbox Interaction 


Mailboxes are virtual I/O devices used to communicate between processes. 
The terminal I/O driver can use a mailbox to communicate with a user 
process. Chapter 7 describes the mailbox driver. 


A user program can. use the Assign I/O Channel ($ASSIGN) system service 
to associate a mailbox with one or more terminals. The terminal driver 
sends messages to this mailbox when terminal-related events that require 
the attention of the user image occur. 


Mailboxes used in this way carry status messages, not terminal data, from 
the driver to the user program. For example, when data is received from 
a terminal for which no read request is outstanding (unsolicited data), a 
message is sent to the associated mailbox to indicate data availability. On 
receiving this message, the user program reads the channel assigned to 
the terminal to obtain the data. Messages are sent to mailboxes under the 
following conditions: | 


¢ Unsolicited data in the type-ahead buffer. The use of the associated 
mailbox can be enabled and disabled as a subfunction of the read 
and write requests (see Sections 8.4.1 and 8.4.2). (Initially, mailbox 
messages are enabled on all terminals. This is the default state.) 
Thus, the user process can enter into a dialogue with the terminal 
after an unsolicited data message arrives. Then, after the dialogue 
is over, the user process can reenable the unsolicited data message 
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function on the last I/O exchange. Only one message is sent between 
read operations. 


e Terminal hangup. When a remote line loses the carrier signal, it hangs 
up; a message is sent to the mailbox. When hangup occurs on lines 
that have the characteristic TT$M_REMOTE set, the line returns to 
local mode. 


¢ Broadcast messages. If the characteristic TT2$M_BRDCSTMBX is 
set, broadcasts sent to a terminal are placed in the mailbox (this is 
independent of the state of TT$M_NOBRDCST). 


Messages placed in the mailbox have the following content and format (see 
Figure 8-2): 


¢ Message type. The codes MSG$_TRMUNSOLIC (unsolicited data), 
MSG$_TRMHANGUP (hangup), and MSG$_TRMBRDCST (terminal 
broadcast) identify the type of message. Message types are identified 
by the $MSGDEF macro. 


e Device unit number to identify the terminal that sent the message. 
¢ Counted string to specify the device name. 
¢ Controller name. 


¢ Message (for broadcasts). 


Figure 8-2 Terminal Mailbox Message Format 





31 16 15 87 0 

. 
Controller Name * 4 

eines 

a 

iv 





Broadcast Message Length 
Broadcast 
= | T Message 


* Does not include the colon (:) character. 


ZK-0686-—GE 


Interaction with a mailbox associated with a terminal occurs through 
standard QIO functions and ASTs. Therefore, the process need not have 
outstanding read requests to an interactive terminal to respond to the 
arrival of unsolicited data. The process need only respond when the 
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mailbox signals the availability of unsolicited data. Chapter 7 contains an 
example of mailbox programming. 


The ratio of terminals to mailboxes is not always one to one. One user 
process can have many terminals associated with a single mailbox. 


8.2.5 Autobaud Detection 


If you specify the /AUTOBAUD qualifier with the SET TERMINAL 
command, automatic baud rate detection is enabled, allowing the terminal 
baud rate to be set when you log in. The baud rate is set at login by 
pressing the Return key two or more times separated by an interval of 

at least one second. (Pressing a key other than Return might detect the 
wrong baud rate; if this occurs, wait for the login procedure to time out 
before continuing.) The supported baud rates are 110, 150, 300, 600, 1200, 
1800, 2400, 3600, 4800, 9600, and 19200. Parity is allowed on these lines. 


The autobaud function works with either even parity or no parity, but not 
with odd parity. If a line is set to even parity and has seven bits of data, 
the line automatically switches to no parity if a terminal not generating 
parity attempts to log in. 


The SET TERMINAL qualifier /EIGHT_BIT specifies that the terminal 
uses eight-bit ASCII code. /NOEIGHT_BIT, which is the default, specifies 
seven-bit ASCII code. (If parity is specified, the parity bit is separate from 
the data bits.) The optimal settings for automatic baud rate detection on 
Digital terminals are /NOEIGHT_BIT/PARITY=EVEN or /EIGHT_BIT 
/NOPARITY, although automatic baud rate detection also works with other 
combinations, such as /NOEIGHT_BIT/NOPARITY. 


Table 8-6 describes the terminal characteristic TT2$M_AUTOBAUD, 
which allows the baud rate to be set automatically at login. 


Specifying the /FRAME qualifier with the SET TERMINAL command 
is not usually recommended. The terminal driver selects the frame size 
(the number of data bits that the device can transmit) based on how the 
/PARITY and /EIGHT BIT qualifiers are set. It might be necessary to 
change these values if the terminal is not made by Digital. 


8.2.6 Out-of-Band Control Character Handling 


All control characters (0 through 1F hexadecimal) can be enabled as out- 
of-band characters. Typing one of these characters immediately delivers 
an AST to the requesting process. DCL uses this mechanism to sense 
whether CTRL/T has been entered. Out-of-band character options allow 
using the IO$M_INCLUDE function modifier to include the character in 
the data stream and the IO$M_TT_ABORT function modifier to abort the 
current input or output operation. 
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You can obtain information on terminal characteristics by using the Get 
Device/Volume Information ($GETDVI) system service. (See the VMS 
System Services Reference Manual.) The sense mode function provides an 
alternative means to obtain terminal characteristics; see Section 8.4.5. 


$GETDVI returns terminal characteristics when you specify the item codes 
DVI$_DEVCHAR, DVI$_DEVDEPEND, and DVI$_DEVDEPEND2. Tables 
8—4, 8-5 and 8-6 list these characteristics. Terminal characteristics are 
normally set during system generation to any one of, or a combination of, 
the values listed in Table 8-5. DVI$_DEVDEPEND returns a longword 
field in which the three low-order bytes contain the device-dependent 
characteristics and the high-order byte contains the page length. Page 
length can have a value in the range of 0 through 255. The $DEVDEF 
macro defines the device-independent characteristics, the $TTDEF macro 
defines the device-dependent characteristics, and the $TT2DEF macro 
defines the extended device-dependent characteristics. 


DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device 
type names, which are defined by the $DCDEF and $TTDEF macros, 
respectively. The device class for terminals is DC$_TERM. The terminal 
model determines the device type. For example, the device type for the 
VT240 is TT$_VT200_SERIES. DVI$_DEVBUFSIZ returns the page 
width, which can be a value in the range of 1 through 511. The driver does 


not accept a value of 0. 


Table 8-4 Terminal Device-Independent Characteristics 


Characteristic 


DEV$M_AVL 

DEV$M_CCL 
DEV$M_DET 
DEV$M_IDV 

DEV$M_ODV 
DEV$M_OPR 
DEV$M_REC 
DEV$M_RTT 
DEV$M_SPL 
DEV$M_TRM 
DEV$M_NET 


Meaning 


Terminal is on line and available. 
Carriage control is enabled. 
Terminal is detached. 

Terminal is capable of input. 


_ Terminal is capable of output. 


Terminal is enabled as an operator console. 
Device is record-oriented. 

Terminal has remote terminal UCB extension. 
Device is spooled. 

Device is a terminal. 

Terminal line is allocated for VAX-DECnet use. 
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Table 8-5 Terminal Characteristics 


Value’ 


TT$M_CRFILL 


TT$M_EIGHTBIT 


TT$M_ESCAPE 
TT$M_HALFDUP 


TT$M_HOSTSYNC 


TT$M_LFFILL 


TT$M_LOWER 


TT$M_MBXDSABL 


TT$M_MECHFORM 
TT$M_MECHTAB 


TT$M_MODEM 


TT$M_NOBRDCST 
TT$M_NOECHO 
TT$M_NOTYPEAHD 


Meaning 


Terminal requires fill after the Return key is pressed (the fill type can be specified by the 
set mode function P4 argument). 


Terminal uses the eight-bit ASCII character set (see Appendix B). Terminals without this 
characteristic use the seven-bit ASCII code. In this case, the eighth bit is masked out on 
received characters and is ignored on output characters. The eighth bit is meaningful only 
if TT$M_EIGHTBIT is set. 


Terminal generates escape sequences (see Section 8.2.1.4). Escape sequences are 
validated for syntax. 


Terminal is in half-duplex mode (see Section 8.2.2.1). All read and write requests are 
executed sequentially. 


The host system is synchronized to the terminal. CTRL/Q and CTRL/S are used to control 
data flow and thus keep the type-ahead buffer from filling. TT$M_HOSTSYNC should 
always be set on LAT terminals. 


Terminal requires fill after the line-feed character is processed. (The fill can be specified 
by the set mode P4 argument.) 


Terminal has the lowercase character set. Unless the terminal is in the PASTHRU 
mode or IO$M_NOFORMAT is specified, all input and echoed lowercase characters 
(hexadecimal 61 to 7A) are converted to uppercase if TT$M_LOWER is not set. (The 
character ALTMODE (decimal 125 and 126, or hexadecimal 7D and 7E) converts to 
ESCAPE on terminals that do not have the lowercase characteristic TT$M_LOWER set.) 


Mailboxes associated with the terminal do not receive notification of unsolicited input 
or hangup (see Section 8.2.3). This bit can be set by the IO$M_DSABLMBxX function 
modifier for read requests and cleared by the IO$M_ENABLMBxX function modifier for 
write requests. 


Terminal has mechanical form feed. The terminal driver passes form feeds directly to the 
terminal instead of expanding to line feeds. 


Terminal has mechanical tabs and is capable of tab expansion. To accomplish correct line 
wrapping, the terminal driver assumes there are eight spaces between tab stops. 


Terminal line is connected to a modem. If TT$M_MODENM is set, the terminal driver 
automatically handles modem control. If TT$M_MODEM is not set, all modem signals are 
ignored. If TT$M_MODENM is set and then cleared, a hangup is declared on the terminal 
line if that line is in the remote state (TT$M_REMOTE is set). If DTR and RTS are set 
with 1O$¢ SETMODE!IO$M_SET_MODEMI!IO$M_MAINT on a nonmodem port, DTR and 
RTS goes off and then back on when the port is set for modem. 


TT$M_MODEM is not supported for LAT devices. 
Terminal does not receive any broadcast messages. 
Input characters are not echoed on this terminal line (see Section 8.2.1.5). 


Data must be solicited by a read operation. Data is lost if received in the absence of 
an outstanding read request (if it is unsolicited data). Disables type-ahead feature (see 
Section 8.2.1.5). If this characteristic is set, login attempts on this line are disabled. See 
Section 8.2.3.1 for information on modem signal control. 


‘Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit mask whose bit corresponds to the 
specific field; TT$V_ is a bit number. 
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Table 8-5 (Cont.) Terminal Characteristics 


Value’ 
TT$M_READSYNC 


TT$M_REMOTE 


TT$M_SCOPE 
TT$M_TTSYNC 


TT$M_WRAP 


Meaning 


Read synchronization is enabled. The host explicitly solicits all read operations by 
entering a CTRL/Q and terminates the operation by entering a CTRL/S. 
TT$M_READSYNC is not applicable to LAT terminals. 


Dial-up characteristic is enabled. The terminal returns to local mode when a hangup 
occurs on the terminal line (see Section 8.2.3). This characteristic cannot be changed; it 
is only informational. 


Terminal is a video screen display (CRT terminal), for example, the VT100 or VT240. 


The terminal is synchronized to the host system. Output to the terminal is controlled 
by terminal-generated CTRL/Q and CTRL/S. TT$M_TTSYNC is not applicable to LAT 
terminals unless TT$M_PASTHRU is set and TT$M_TTSYNC is disabled, in which case 
the LAT session is placed in PASSALL mode. 


A carriage-return/line-feed combination should be inserted if the cursor moves beyond the 
right margin. If TT$M_WRAP is not set, no carriage-return/line-feed combination is sent. 
The VMS operating system does not support hardware-provided wrapping functions. 


'Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit mask whose bit corresponds to the 
specific field; TT$V_ is a bit number. 


Table 8-6 Extended Terminal Characteristics 


Value’ 


TT2$M_ALTYPEAHD 


TT2$M_ANSICRT 


TT2$M_APP_KEYPAD 
TT2$M_AUTOBAUD 


Meaning 


Alternate type-ahead buffer size is enabled. Use the alternate type-ahead buffer 
size specified during system generation (see Section 8.2.1.5). If a type-ahead buffer 
already exists for a terminal line, there is no effect when this characteristic is set 
for that line. TT2$M_ALTYPEAHD should be set prior to using the terminal, such 
as in the startup command procedure. You can only set TT2$M_ALTYPEAHD; this 
characteristic cannot be cleared until the system is rebooted. 


ANSI CRT terminal is enabled. This characteristic is set by the SET TERMINAL 
command. TT2$M_ANSICRT is a subset of the ANSI standard with no DIGITAL- 
private escape sequences (see Appendix B). It is also a subset of the VT100-family 
terminals (because TT2$M_ANSICRT is a subset of TT2$M_DECCRT) and the 
VT100. Terminals with this characteristic must provide a display of at least 24 lines, 
each with 80 columns. 


Notifies application programs of state to set the keypad to when exiting. 


Automatic baud rate detection is enabled. This characteristic allows the baud rate 
to be set automatically when you log in. (The baud rate is set when one or more 
carriage returns are entered during the login procedure.) Terminals are set to a 
permanent speed of 9600 baud. If TT2SM_AUTOBAUD is specified, the permanent 
speed must not be changed while this characteristic is in use on a given terminal 
line. See Section 8.2.5 for additional information on automatic baud rate detection. 


‘Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a bit mask in which the bit set 
corresponds to the specific field; TT2$V_ is a bit number. 
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Table 8-6 (Cont.) Extended Terminal Characteristics 


Value" 
TT2$M_AVO 


TT2$M_BLOCK 


TT2$M_BRDCSTMBX 


TT2$M_DECCRT 


TT2$M_DECCRT2 


TT2$M_DIALUP 
TT2$M_DISCONNECT 


TT2$M_DMA 
TT2$M_DRCS 


TT2$M_EDIT 


TT2$M_EDITING 


Meaning 


Advanced video is enabled. This characteristic provides the terminal with blink, 
bold, and flashing fields as well as a full screen of 132 character lines. 
TT2$M_AVO is set by the SET TERMINAL command. Appendix B lists the valid 
escape sequences for terminals with the TT2$M_AVO characteristic. 


Block mode is enabled. This characteristic is set by the SET TERMINAL command. 
TT2$M_BLOCK defines additional ANSI-defined and DIGITAL-private escape 
sequences (see Appendix B). Terminals with this characteristic are capable of local 
editing and block mode transmission (XON/XOFF flow control must be honored), 
and have protected fields. If the terminal is used for large amounts of block input, 
TT2$M_ALTYPEAHD should also be specified. 


Mailbox broadcasts messages. Broadcast messages are sent to an associated 
mailbox, if one exists. 


DIGITAL CRT terminal. This characteristic is set by the SET TERMINAL command 
for all terminals that are upward-compatible with VT100-family terminals. 
TT2$M_DECCRT is a superset of TT2$M_ANSICRT. Additional ANSI-defined as 
well as most DIGITAL-private escape sequences are allowed for terminals with 
this characteristic (see Appendix B); maintenance modes, VT52 mode, and the 
use of the LED displays are not defined by TT2$M_DECCRT. Not all VT100-family 
terminals implement these features. The presence of the advanced video feature 
cannot be assumed because it is a VT100 option. This restricts the use of graphics 
attributes. However, the TT2$M_AVO characteristic can be used to determine 
whether additional graphic attributes are available. 


DIGITAL CRT terminal. This characteristic is set by the SET TERMINAL command 
for all terminals that are upward-compatible with VT200-family terminals. 
TT2$M_DECCRT2 is a superset of TT2$M_DECCRT. 


Terminal is a dial-up line. Used by LOGINOUT for the disable dial-up control. 


Allows terminal disconnect when a hangup occurs (that is, when modem signals 
are lost, when the DCL commands DISCONNECT, or CONNECT/CONTINUE are 
entered, or when the BREAK key is pressed on a terminal that has the 
TT2$M_SECURE characteristic). These terminals are created as VTAn:. (See 
the description for the DCL command CONNECT/DISCONNECT in the VMS DCL 
Dictionary.) 


DMA mode. This characteristic enables the use of DMA mode for asynchronous 
DMA multiplexers. It is ignored by non-DMA controllers. 


Terminal supports loadable character fonts. This characteristic is set with the DCL 
command SET TERMINAL/SOFT_CHARACTERS. 


Terminal edit. This characteristic is set by the SET TERMINAL command for all 
terminals that support ANSI-defined advanced editing functions. These functions 
include the ability to insert or delete a line and the ability to insert or delete 
characters in an existing line. Terminals with this characteristic are a superset of 
TT2$M_DECCRT. Appendix B lists the valid escape sequences for terminals with 
the TT2$M_EDIT characteristic. 


Line editing is allowed. 


'Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a bit mask in which the bit set 
corresponds to the specific field; TT2$V_ is a bit number. 
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Table 8-6 (Cont.) Extended Terminal Characteristics 


Value’ 
TT2$M_FALLBACK? 


TT2$M_HANGUP 


TT2$M_INSERT 
TT2$M_LOCALECHO 


TT2$M_MODHANGUP 


TT2$M_PASTHRU 


TT2$M_PRINTER 
TT2$M_REGIS 
TT2$M_SIXEL 
TT2$M_SECURE 
TT2$6M_SETSPEED 


TT2$6M_SYSPWD 


TT2$M_XON 


Meaning 


Output is transformed from the eight-bit multinational character set to a seven-bit 
ASCII character set on terminals that do not support the eight-bit character set (see 
Appendix B). 


Terminal hangup. Terminal lines connected through modems are hung up when a 
process logs out or is deleted. The state of this characteristic cannot be changed 
unless TT2$M_MODHANGUP is enabled or the process has either LOG_IO or 
PHY_IO privilege. 


Sets default mode for insert or overstrike at the beginning of each read operation. 


Local echo. This characteristic is used with TT$M_NOECHO. If both characteristics 
are set, only terminators and special control characters are echoed. Use of this 
mode is restricted to command line read operations. Application programs 

that use the IO$M_NOECHO function modifier will not necessarily work if 
TT2$M_LOCALECHO is set. Local echo is also not compatible with line editing 
(TT2$M_EDITING). 


Modify hangup. If specified, TT2$M_HANGUP can be modified without privilege. 
Otherwise, logical or physical I/O privilege is required. 


Terminal is in PASTHRU mode; all input and output data is in seven- or eight- 
bit binary format (no data interpretation occurs). Data is terminated when the 
buffer is full or when the data that is read matches the specified terminator. If 
the characteristic TT$M_TTSYNC is set, CTRL/S and CTRL/Q interpretation does 
occur. 


DIGITAL CRT terminal with a local printer port. 
ReGIS graphics. The terminal supports the ReGIS graphics instruction set. 
SIXEL graphics. The terminal supports the SIXEL graphics instruction set. 


For use with nonmodem, nonautobaud lines. This characteristic guarantees 
that no process is connected to the terminal after the BREAK key is pressed. 
lf TT2$M_SECURE is not set, BREAK is a null key. 


Set speed. If specified, either LOG_IO or PHY_IO privilege is required to change 
terminal speed. TT2$M_SETSPEED is not supported for LAT devices. 


System password. This characteristic specifies that the login procedure should 
require the system password before the user name prompt is displayed. 


XON/XOFF control. If a set mode function is performed on a terminal in the 
CTRL/S state, and if TT2$M_XON is set, output is resumed. Users should note 
that the driver will attempt to resume stopped (XOFF) output on the line. However, 
restarting the output may not be successful in all cases. The XON/XOFF feature 
does not work on all terminals, for example, the VT220. 


‘Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_, TT2$M_ is a bit mask in which the bit set 
corresponds to the specific field; TT2$V_ is a bit number. 


2if an attempt is made to turn on TT2$V_FALLBACK for a disconnected virtual terminal (_VTAx:) or if the Terminal Fallback 
Facility (TFF) has not been activated, the status code SS$_BADPARAM is returned. For more information on TFF, refer to the 
VMS Terminal Fallback Utility Manual. 
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8.3.1. Terminal Characteristics Categories 


The set mode and set characteristics functions (see Section 8.4.3) and 
the DCL command SET TERMINAL are used to change terminal 
characteristics. The VMS DCL Dictionary describes the SET TERMINAL 
command. 


To customize terminal behavior and usage, the VMS operating system 
divides terminal characteristics into the following categories: 


Format effectors—The following characteristics allow the user to 
specify terminal-dependent formatting requirements: 


TT$M_CRFILL TT$M_EIGHTBIT TT$M_LFFILL 
TT$M_LOWER TT2$M_LOCALECHO TT$M_MECHFORM 
TT$M_MECHTAB TT$M_NOECHO TT$M_SCOPE 
TT$M_WRAP 


Generic terminal capabilities—The following characteristics specify 
generic terminal features available to applications programs: 


TT2$M_ANSICRT TT2$M_AVO TT2$M_BLOCK 
TT2$M_DECCRT TT2$M_DECCRT2 TT2$M_DRCS 
TT2$M_EDIT TT2$M_PRINTER TT2$M_REGIS 
TT2$M_SIXEL 


Their use allows execution of these programs without knowledge of the 
actual terminal type. For example, a program should check for 
TT2$M_DECCRT rather than for VT100 or VT101. 


Protocol—The following characteristics control protocols used by the 
terminal: 

TT$M_ESCAPE TT$M_HALFDUP TT$M_HOSTSYNC 
TT2$M_PASTHRU TT$M_TTSYNC 

System management—tThe following characteristics, normally set only 


at system startup, allow the system manager to regulate terminal 
usage: 


TT2$M_ALTYPEAHD TT2$M_AUTOBAUD TT2$M_DIALUP 
TT2$M_DISCONNECT TT2$M_DMA TT2$M_HANGUP 
TT$M_MODEM TT$M_NOTYPEAHD TT2$M_MODHANGUP 
TT2$M_SECURE TT2$M_SETSPEED TT2$M_SYSPWD 


User preference—The following characteristics allow you to customize 
the terminal operating mode: 


TT2$M_APP_KEYPAD TT2$M_FALLBACK TT2$M_EDITING 
TT2$M_INSERT TT$M_NOBRDCST 


Miscellaneous—The following characteristics provide greater program 
control of terminal operations: 


TT2$M_BRDCSTMBX  TI$M_MBXDSABL TT2$M_XON 
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The basic terminal I/O functions are read, write, set mode, set 
characteristics, sense mode, and sense characteristics. All I/O functions 
can take function modifiers. 


When a read function code is issued, the user-specified buffer is filled 
with characters from the associated terminal. The VMS operating system 
provides the following read function codes: 


¢ JIO$ READVBLK—Read virtual block 
¢ IO$ READLBLK—Read logical block 
¢ IO$_READPROMPT—Read with prompt 


Read operations are terminated if either of the following two conditions 
occurs: 


e The user buffer is full. 


¢ The received character is included in a specified terminator mask (see 
Section 8.4.1.2). 


The following device- or function-dependent arguments are used with the 
read function codes. The codes can take all six arguments (P1 through 
P6) on QIO requests. The descriptions for these arguments differ when 
itemlist read operations are performed (see Section 8.4.1.3). 


¢ Pi—The starting virtual address of the buffer that is to receive the 
data read. 


e P2—The size of the buffer that is to receive the data read in bytes. (A 
- system generation parameter, MAXBUF, limits the maximum size of 
the buffer.) 


e P3—Read with timeout, timeout count (see Table 8-7, IO$M_TIMED). 
¢ P4—The read terminator descriptor block address (see Section 8.4.1.2). 


¢ P5—The starting virtual address of the prompt buffer that is to be 
written to the terminal; for read with prompt operations using the 
IO0$_READPROMPT function code. (This argument is specified as a 
value, rather than an address as in the P1 argument.) 


¢ P6—The size of the prompt buffer that is to be written to the terminal; 
for read with prompt operations using the IO$_READPROMPT 
function code. 


In a read with prompt operation, the P5 and P6 arguments specify the 
address and size of a prompt string buffer containing data to be written 
to the terminal before the input data is read. In a read with prompt 
operation, both read and write operations are performed on the specified 
terminal. The prompt string buffer is formatted like any other write 
buffer. If cursor position specifiers are supplied, they are not interpreted 
by the driver but passed to the terminal. 
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During a read with prompt operation, pressing CTRL/O (which is turned 
off at the start of any read operation) stops the prompt string. If you press 
either CTRL/U or CTRL/X, the entire prompt string is written out again, 
and the current input is ignored. If you press CTRL/R, the current prompt 
string and input are written to the terminal. 


Depending on the terminal type and your input, the prompt string can be 
very simple or quite complex—from single command prompts to screen fills 
followed by input data. Digital recommends that prompt strings contain 
only one leading line feed. 


In PASTHRU mode, data received from the associated terminal is placed 
in the user buffer as binary information without interpretation. (Prompts 
are not refreshed after a broadcast in PASTHRU mode.) 


Function Modifier Codes for Read QIO Functions 


Eight function modifiers can be specified with IO$_READVBLK, 
I0$_READLBLK, and I0$_READPROMPT. Table 8-7 lists these function 
modifiers and IO$_EXTEND, which is described in Section 8.4.1.3. All 
read function modifiers are supported for LAT devices. 


Table 8-7 Read QIO Function Modifiers for the Terminal Driver 





Code 


Consequence 





lO$M_CVTLOW 


IO$M_DSABLMBX 
l\O$M_ESCAPE 
lO$M_EXTEND 


IO$M_NOECHO 


lO$M_NOFILTR 


l\O$M_PURGE 
l\O$M_TIMED 


Lowercase alphabetic characters (hexadecimal 61 to 7A) are converted to uppercase 
when transferred to the user buffer or echoed. This characteristic is used only for 
lO$_READLBLK, 10$_READVBLK, and l1O$_READPROMPT. 


The mailbox is disabled for unsolicited data. 


A valid ANSI escape sequence is recognized as a valid delimiter for the read operation. 
The TT$M_ESCAPE characteristic is overridden by this modifier for the current read 
operation. 


This characteristic provides additional functionality for read operations (see 
Section 8.4.1.3). Do not specify IO$M_EXTEND with other function modifiers. 


Characters are not echoed as they are entered at the keyboard. The terminal line can 
also be set to a “no echo” mode by the set mode characteristic TT$M_NOECHO, which 
inhibits all read operation echoing. Setting IO$M_NOECHO also disables line editing. 


The terminal does not interpret CTRL/U, CTRL/R, or DEL. They are passed to the user. 
IO$M_NOFILTR explicitly disables line editing. 


The type-ahead buffer is purged before the read operation begins. 


The P3 argument specifies the maximum time (seconds) that can elapse between 
characters received from the terminal (the timeout value for the operation). Because 
driver timing operates on a one-second timer, a two-second timeout must be specified to 
guarantee a one-second wait. The timer starts when the prompt echo is started. If the 
read time exceeds the time specified in P3, a timeout error (SS$_TIMEOUT) is returned 
in the read IOSB. All input characters received before the read operation timed out are 
returned in the user’s buffer. 


(continued on next page) 
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Table 8-7 (Cont.) Read QIO Function Modifiers for the Terminal Driver 


Code 


lO$M_TRMNOECHO 


Consequence 


A read with timeout operation, in which the timeout value is 0, empties the type-ahead 
buffer into the user buffer until the proper termination condition is reached (buffer full, 
termination character detected, or type-ahead buffer empty). The read operation then 
returns the count of characters read and, if a terminator is read, SS$_ NORMAL; SS$_ 
TIMEOUT is returned if no terminator is read. In either case the offset to terminator in the 
lOSB always indicates the number of characters read. Note that the timer starts when the 
prompt echo is started. 


If a read operation is interrupted by either a broadcast write or a synchronous write 
request, the timer operation is restarted. 


The termination character (if any) is not echoed. There is no formal terminator if the 
buffer is filled before the terminator is typed. 


8.4.1.2 Read Function Terminators 
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The P4 argument to a read QIO function either specifies the terminator 
set for the read function or points to the location containing the terminator 
set. If P4 is 0, all ASCII characters with a code in the range 0 through 
31 (hexadecimal 0 through 1F) except LF, VT, FF, TAB, and BS, are 
terminators (see Appendix B). This is the VMS RMS standard terminator 
set. The delete character (hexidecimal 7F) and eight-bit controls in the 
range 128 through 159, and 255 (hexidecimal 80 through 9F, and FF) are 
also terminators. If line editing is enabled, only RETURN, CTRL/Z, or an 
escape sequence terminates a read operation. 


If P4 does not equal 0, it contains the address of a quadword that either 
specifies a terminator character bit mask or points to a location containing 
that mask. (Note that if P4 references an address in a MACRO program, 
a number sign (#) must precede the address, for example, P4=#TMASK.) 
The quadword has a short form and a long form, as shown in Figure 8-3. 
In the short form, the correspondence is between the bit number and the 
binary value of the character; the character is a terminator if the bit is 
set. For example, if bit 0 is set, NULL is a terminator; if bit 9 is set, TAB 
is a terminator. If a character is not specified, it is not a terminator. Since 
ASCII control characters are in the range 0 through 31, the short form can 
be used in most cases. 


The long form allows use of a more comprehensive set of terminator 
characters. Any mask equal to or greater than one byte is acceptable. For 
example, a mask size of 16 bytes allows all seven-bit ASCII characters 

to be used as terminators; a mask size of 32 bytes allows all eight-bit 
characters to be used as terminators for eight-bit terminals. 


If the terminator mask is all zeros, there are no specified terminators. The 
read operation ends when the specified number of bytes (characters) have 
been transferred to the input buffer. 


Certain control keys will not act as terminators unless IO$M_NOFILTR 
is specified or the line has the TT2$M_PASTHRU characteristic (see 
Section 8.2.1.2.). 
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Figure 8-3 Short and Long Forms of Terminator Mask Quadwords 










SHORT: 


31 0 
Terminator Character Bit Mask 


31 16 15 


(Not Used) Mask Size in Bytes 
Address of Mask 


ZK-0689-GE 










LONG: 


8.4.1.3 Itemlist Read Operations 


Note: 


Itemlist read operations provide expanded software features to read Qio 
requests. The VMS operating system provides the following combination 
of function code and modifier: 


¢ I0$_READVBLK!IO$M_EXTEND—Itemlist read virtual block 


No other function modifiers can be specified in an itemlist read request. 


Itemlist read features supported by the terminal driver are not 
supported by all DECNET terminal emulators. 


The itemlist read function code and modifier combination takes the 
following device- or function-dependent arguments: 


e Pi—tThe starting virtual address of the buffer that is to receive the 
data read 


e P2—tThe size of the buffer that is to receive the data read in bytes. If 
required, the P2 size includes additional space for an overflow buffer 


to hold an escape sequence terminator (see item code 
TRM$_ESCTRMOVR in Table 8-8). 


e P3—The access mode at which the itemlist is to be probed (optional) 
e P5—The address of the itemlist buffer 
¢ P6—tThe length in bytes of the itemlist buffer 
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P4 is not meaningful for itemlist read operations. P5 points to a series of 
item descriptors. Figure 8—4 shows the format for these descriptors. You 
cannot repeat the same item code in the same item list. 


Figure 8-4 Itemlist Read Descriptor 


31 16 15 0 


Item Code Buffer Length 
Buffer Address or Immediate Data 
Return Address * 


* Must be zero. 










Itemlist Read — P5 Buffer 


ZK-1305-GE 


Table 8-8 lists the item codes that can be specified in the first longword of 
the item descriptors. 


Table 8-8 Item Codes for Itemlist Read Operations for the Terminal Driver 


Item Code 


Meaning 





TRM$_ALTECHSTR 


Note: 


TRM$_EDITMODE 


TRM$_ESCTRMOVR 
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Alternate echo string. The buffer length word contains the length of the string. The data 
address word contains the address of the string. The alternate echo string is written to 
the terminal after the first character is entered. 


This item code for character validating read mode (TRM$K_EM_ 
RDVERIFY) editing only. 


Extended editing modes. The immediate data longword specifies extended editing mode 

values. The buffer length word must be zero. The following editing modes are supported: 

TRM$K_EM_DEFAULT Normal read mode. This is the default if TRM$_ EDITMODE 
is not present in the itemlist. 


TRM$K_EM_RDVERIFY Character validating read mode. See Section 8.4.1.4. 


Escape terminator overflow size. Specifies the number of bytes that may be used to 
hold an escape sequence terminator. This number should be included in P2, the buffer 
size argument, in addition to the space required for the data to be read. Note that this 
overflow area is for the terminator only; it is not available for user data. 


TRM$_ESCTRMOVR is useful in preventing partial escape errors, which return 
SS$_PARTESCAPE. This overflow buffer ensures that all the characters in an escape 
sequence terminator will fit in the user buffer, thus eliminating the need for additional 
single-character read operations. 


(continued on next page) 
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Table 8-8 (Cont.) Item Codes for Itemlist Read Operations for the Terminal Driver — 


item Code 


TRM$_FILLCHR 


Note: 
TRM$_INIOFFSET 


TRM$_INISTRNG 


TRM$_MODIFIERS 


Meaning 


A two-byte value that indicates the fill and clear character for TRM$K_EM_RDVERIFY. 
The first byte of the immediate data longword specifies the clear character; the second 
byte specifies the fill character. 


This item code for character validating read mode (TRM$K_EM_ 
RDVERIFY) editing only. 


Indicates the character in the initial string where echoing starts. The immediate data 
longword specifies the character. 


Specifies a string to preload into the read buffer (P1). The buffer length word contains the 
length of the string. The data longword contains the address of the string. 
TRM$_INISTRNG must be specified if the edit mode is TRM$K_EM_RDVERIFY, and 
must be the same length as specified by TRM$_PICSTRNG. 


Read modifiers. The immediate data longword contains a 32-bit value that specifies 
modifiers to read operations. The read operations are defined in $TRMDEF. The buffer 
length word must be zero. The following bits are defined: 

TRM$M_TM_ARROWS The terminal interprets the left and right arrow keys 
(TRM$K_EM_RDVERIFY mode only). The arrow keys 
are not put in the buffer and do not terminate the read. 
TRM$_ESCTRMOVR must be greater than or equal to 5. 


TRM$M_TM_AUTO_TAB This bit creates an auto-tab mode field (TRM$K_EM_ 
RDVERIFY mode only). 
TRM$M_TM_CVTLOW Lowercase alphabetic characters (hexadecimal 61 to 7A) 


are converted to uppercase when transferred to the user 
buffer or echoed. 


TRM$M_TM_DSABLMBX The mailbox is disabled for unsolicited data and for 
receiving hangup messages. 


TRM$M_TM_ESCAPE A valid ANSI escape sequence is recognized as a valid 
delimiter for the read operation. 

TRM$M_TM_NOCLEAR Fill characters are not replaced with clear characters 
after a nonfill character occurs (TRM$K_EM_RDVERIFY 
mode only). 

TRM$M_TM_NOECHO Characters are not displayed as they are entered at the 
keyboard. 

TRM$M_TM_NOEDIT This bit inhibits advanced editing for this read operation. 

TRM$M_TM_NOFILTR The terminal does not interpret DEL, CTRL/U, or 


CTRL, but passes them to you. This characteristic 
explicitly disables line editing. 





(continued on next page) 
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Table 8-8 (Cont.) 


Item Code 


Meaning 


TRM$M_TM_NORECALL 


TRM$M_TM_OTHERWAY 


TRM$M_TM_PURGE 
TRM$M_TM_R_JUST 


TRM$M_TM_TERM_ARROW 


TRM$M_TM_TERM_DEL 


TRM$M_TM_TOGGLE 


TRM$M_TM_TIMED 


TRM$M_TM_TRMNOECHO 


Item Codes for Itemlist Read Operations for the Terminal Driver 


This bit inhibits command recall (CTRL/B) by the terminal 
driver. 


This bit sets left-justify fields to insert mode and right- 
justify fields to overstrike mode (TRM$K_EM_RDVERIFY 
mode only). TRM$M_TM_TOGGLE must equal 1. 


The type-ahead buffer is purged before the read 
operation begins. 


This bit creates a right-justified field (TRM$K_EM_ 
RDVERIFY mode only). 


The read operation is terminated when the left arrow key 
is pressed at the left margin or when the right arrow key 
is pressed at the right margin (TRM$K_EM_RDVERIFY 
mode only). TRM$M_TM_ARROWS must be enabled. 


The read operation is terminated when the DELETE key 
is pressed at the left margin (TRM$K_EM_RDVERIFY 
mode only). 


Enables CTRL/A to function as a toggle key between 
insert mode and overstrike mode (TRM$K_EM_ 
RDVERIFY mode only). Left-justify insert mode shifts 
characters to the right; right-justify insert mode shifts 
characters to the left. Shifted characters are not checked 
for validity in their new positions. 


TRM$_TIMEOUT specifies the maximum time (seconds) 
that can elapse between characters received from the 
terminal; that is, the timeout value for the operation. 
TRM$M_TM_TIMED is assumed set if TRM$_TIMEOUT 
is included in the itemlist. 


The termination character (if any) is not displayed. There 
is no formal terminator if the buffer is filled before the 
terminator is typed. 


Note: All other bits must be zero. 
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Table 8-8 (Cont.) Item Codes for Itemlist Read Operations for the Terminal Driver 





Item Code Meaning 


TRM$_PICSTRNG Character validation string. The buffer length word contains the length of the string, which 
must be the same as the length specified by TRM$_INISTRNG. The data address word 
contains the address of the string. TRM$_PICSTRNG must be specified if the edit mode 
is TRM$K_EM_RDVERIFY. 


Note: This item code for character validating read mode (TRM$K_EM_ 
RDVERIFY) editing only. 


The format of the character validation string is one byte per input character. Each byte is 
a bit mask. The following values are provided: 


Value Meaning 
TRM$M_CV_UPPER Uppercase alphabetic 
TRM$M_CV_LOWER Lowercase alphabetic 


TRM$M_CV_NUMERIC Numeric (0 - 9) 
TRM$M_CV_NUMPUNC Numeric punctuation (+ - .) 
TRM$M_CV_PRINTABLE Printable ASCil character 
TRMS$M_CV_ANY Any character 


If no values are set, the corresponding character specified by TRM$_INISTRNG is used. 
Appendix B lists the multinational character set. 

TRM$_PROMPT Specifies a prompt string. The buffer length word contains the length of the prompt. 
The data address word contains the address of the prompt string. See Section 8.4.1 for 
information on how carriage control specifiers in a prompt string are handled. 

TRM$_TERM The buffer length word determines the format of the nondefault terminator mask. If the 
buffer length word is zero, then the data longword is used as a short form mask. If the 
buffer length word is nonzero, then a mask n bytes long is available at the specified 
address. 


TRM$_TIMEOUT Read timeout. See the description of IOSM_TIMED in Table 8-7. 


8.4.1.4 Read Verify Function 
When using the read verify function, the terminal driver performs input 
validation based on character attributes.! Validation is performed one 
character at a time as data is entered. Invalid characters are not echoed, 
and cause the read operation to complete. It is then up to the application 
program to handle the error appropriately. 


The initial string describes the initial contents of the input field. This 
string may consist of data and marker characters. The clear character 
is displayed on the screen for each occurrence of the fill character in the 
initial string buffer. 


The picture string is a string of bytes where each byte corresponds to one 
character of the field being entered. Each byte specifies a mask of legal 
character types for that character position. If the byte is left as zero, then 
that position is a marker character, and the character from the initial 
string is echoed for that position. 


’ Read verification bypasses the optionally specified termination mask (TRM$_TERM). 
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Write 
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For left-justified fields, the prompt data is output to the terminal, followed 
by an optional number (TRM$_INIOFFSET) of initial string characters. 
Leading marker characters are always output following the prompt, 
leaving the cursor at the leftmost data position. As each character is 
entered, it is validated and then echoed, advancing the cursor position. 
Additional marker characters are skipped as they are encountered. If an 
input character fails the validation, the read operation is completed with 
the invalid character as the terminator. 


For right-justified fields, the prompt is output and is followed by the initial 
string. (In general, TRM$_INIOFFSET is set to the length of 
TRM$_INISTRNG for right-justified fields.) The cursor position remains 
one position to the right of the initial string. For proper operation, right- 
justified fields cannot have mixed picture definitions. After each character 
is input, the entire prompt and input fields are output. Therefore, the 
prompt should include a cursor positioning escape sequence. 


The definition of full field is different for left- and right-justified read 
operations. For left-justified fields, full field is detected when the character 
corresponding to the last nonmarker position in the picture string has been 
entered. For right-justified fields, full field is detected when a character 
other than the fill character is shifted into the leftmost, nonmarker 
position in the field. 


If the modifier TRM$M_TM_AUTO_TAB is set in TRM$_MODIFIERS, 
then detection of a full field terminates the read operation. In the event 
of autotab termination, the terminator character in the IOSB is null. If 
the autotab option is not selected, then termination occurs when one more 
character is typed to a full field. Applications can detect this condition 
when the terminating character index is one character beyond the end 

of the field. The extra character is reported as the terminator. In a 
left-justified field the IOSB index to the terminator is zero-based; in a 
right-justified field this index is one-based. 


If a read verify function is interrupted by an asynchronous write operation, 
the read verify is completed with status SS$_OPINCOMPL. 


No line editing functions other than the delete character function are 
supported for read verify. 


Write operations display the ‘contents of a user-specified buffer on the 
associated terminal. The VMS operating system provides the following 
write I/O functions, which are listed with their function codes: 


¢ JO$ WRITEVBLK—Write virtual block 

e¢ I10$ WRITELBLK—Write logical block 

¢ [0$ _WRITEPBLK—Write physical block 

The write function codes can take the following device- or function- 
dependent arguments: 


e Pi—The starting virtual address of the buffer that is to be written to 
the terminal 
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e P2—The number of bytes that are to be written to the terminal (A 
system generation parameter, MAXBUF, limits the maximum size of 
the buffer.) 


e P4—carriage control specifier except for write physical block operations 
(Write function carriage control is described in Section 8.4.2.2.) 


P3, P5, and P6 are not meaningful for terminal write operations. 


In write virtual block and write logical block operations, the buffer (P1 and 
P2) is formatted for the selected terminal and includes the carriage control 
information specified by P4. 


Unless TT$M_MECHFORM is specified, multiple line feeds are generated 
for form feeds. The number of line feeds generated depends on the current 
page position and the length of the page. By producing a carriage return 
after the last line feed, a form feed also moves the cursor to the left 
margin. Multiple spaces are generated for tabs if the characteristics of the 
selected terminal do not include TT$M_MECHTAB (this does not apply to 
write physical block operations). Tab stops occur every eight characters or 
positions. 


CTDRIVER and Buffered Output 


CTDRIVER, a component of the SET HOST facility, buffers output from 
remote terminals in order to package multiple output requests into a 
single network transfer. As a result, control is returned early to the user 
with a status of SS$_NORMAL when the output buffer has been filled and 
successfully queued. 


Note that this output might not be displayed if the user enters an abort 
character or a CTRL/O. 


8.4.2.1 Function Modifier Codes for Write QIO Functions 
Five function modifiers can be specified with IO$_WRITEVBLK, 
10$_WRITELBLK, and IO$_WRITEPBLK. Table 8-9 lists these function 
modifiers. All write function modifiers are supported for LAT devices. 


Table 8-9 Write QIO Function Modifiers for the Terminal Driver 


Code Consequence 


lO$M_BREAKTHRU Allows breakthrough read regardless of the current active 
state. 


lO$M_CANCTRLO Turns off CTRL/O (if it is in effect) before the write operation. 
Otherwise, the data cannot be displayed. 


IO$M_ENABLMBX Enables use of the mailbox associated with the terminal for 
notification that unsolicited data is available. 


lO$M_NOFORMAT Allows you to specify write functions without interpretation or 
format; in effect, the terminal line is in a temporary PASTHRU 
mode. 


(continued on next page) 
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Table 8-9 (Cont.) Write QIO Function Modifiers for the Terminal Driver 
Code Consequence 


IO$M_REFRESH If a read operation is interrupted by a write operation (by 
either a write breakthrough’ or any other type of write), 
the terminal displays the current read data when the read 
function is restarted. 


‘Any interruption caused by the execution of the $BRDCST or the $BRKTHRU system service 
broadcasting messages to terminals is referred to as a “write breakthrough.” 


8.4.2.2 Write Function Carriage Control 
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The P4 argument is a longword that specifies carriage control. Carriage 
control determines the next printing position on the terminal. P4 is 
ignored in a write physical block operation. Figure 8-5 shows the P4 
longword format. 


Only bytes 0, 2, and 3 in the longword are used. Byte 1 is ignored. If 
the low-order byte (byte 0) is not 0, the contents of the longword are 
interpreted as a FORTRAN carriage control specifier. Table 8-10 lists the 
possible byte 0 values (in hexadecimal) and their meanings. 


Figure 8-5 P4 Carriage Control Specifier 


3 2 1 0 
P4: | POSTFIX PREFIX (Not Used) | FORTRAN 
ZK-0690-GE 
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Table 8-10 Write Function Carriage Control (FORTRAN: byte 0 not 


equal to 0) 

Byte 0 Value ASCII 

(hexadecimal) Character Meaning 

20 (space) Single-space carriage control. (Sequence: 
carriage-return/line-feed combination, print 
buffer contents, return’) 

30 0 Double-space carriage control. (Sequence: 
carriage-return/line-feed combination, carriage- 
return/line-feed combination, print buffer 
contents, return’) 

31 1 Page eject carriage control. (Sequence: form 
feed, print buffer contents, return) 

2B + Overprint carriage control; allows double printing 
for emphasis or special effects. (Sequence: 
print buffer contents, return) 

24 $ Prompt carriage control. (Sequence: carriage- 
return/line-feed combination, print buffer 
contents) 

All other Same as ASCII space character: 

values single-space carriage control 


1A carriage-return/line-feed combination is a carriage return followed by a line feed. 


If the low-order byte (byte 0) is 0, bytes 2 and 3 of the P4 longword 

are interpreted as the prefix and postfix carriage control specifiers. The 
prefix (byte 2) specifies the carriage control before the buffer contents are 
printed. The postfix (byte 3) specifies the carriage control after the buffer 
contents are printed. The sequence is as follows: 


1 Prefix carriage control 

2 Print 

3 Postfix carriage control 

The prefix and postfix bytes, although interpreted separately, use the same 
encoding scheme. Table 8-11 shows this encoding scheme in hexadecimal. 


With several exceptions, Figure 8-6 shows the prefix and postfix 
hexadecimal coding that produces the carriage control functions listed 
in Table 8-10. Prefix and postfix coding provides an alternative way to 
achieve these controls. 


In the first example in Figure 8-6, the prefix/postfix hexadecimal coding 
for a single-space carriage control (carriage-return/line-feed combination, 
print buffer contents, return) is obtained by placing the value 1 in the 
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Set Mode 


second (prefix) byte and the sum of the bit 7 value (80) and the return 
value (D) in the third postfix byte. . 


80 (bit 7 = 1) 
+ D (return) 


8D (postfix = return) 


Table 8-11 Write Function Carriage Control (P4 byte 0 = 0) 


Prefix/Postfix Bytes (Hexadecimal) 


Bits 

Bit 7 0-6 Meaning 
0 No carriage control is specified (NULL). 
1-7F Bits 0 through 6 are a count of carriage- 


return/line-feed combinations. 


Bit 7 Bit 6 Bit 5 Bits 0-4 Meaning 


1 0 0 1-1F Output the single ASCII control character 
specified by the configuration of bits 0 
through 4 (seven-bit character set). 

1 1 0 1-1F Output the single ASCII contro! character 
specified by the configuration of bits 0 
through 4, which are translated as ASCII 
characters 128 through 159 (eight-bit 
character set; see Appendix B). 


Set mode operations affect the operation and characteristics of the 
associated terminal line. The VMS operating system provides two types of 
set mode functions: set mode and set characteristics. 


The set mode function affects the mode and temporary characteristics 
of the associated terminal line. Set mode is a logical I/O function and 
requires no privilege.! The following function code is provided: 


¢ I0$_SETMODE 


The set characteristics function affects the permanent characteristics of 
the associated terminal line. Set characteristics is a physical I/O function 
and requires the privilege necessary to perform physical I/O. The following 
function code is provided: 


¢ IO$_SETCHAR 


1 If you do not have LOG_IO or PHY_IO privilege, the terminal driver does not accept a set mode request to 
a terminal that does not have the extended terminal characteristic TT2$M_SETSPEED—even if no request 
for a change of speed is made. Privilege is not required if TT2$M_SETSPEED is set but no attempt to 
change the speed is made. 
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Figure 8-6 Write Function Carriage Control (Prefix and Postfix Coding) 


(Space) Sequence: 


Prefix = NL 
Print 
Postfix = CR 


P4: 


Sequence: 


Prefix = NL, NL 
Print 
Postfix = CR 


"Q" 


P4: 


Sequence: 


Prefix = FF 
Print 
Postfix = CR 


"4 " 


P4: 8 


a Sequence: 


Prefix = NULL 
Print 
1 Postfix = CR 


P4: 


"g" Sequence: 
i oe Prefix = NL 
nn ee 


Print 
Example: Skip 24 lines before printing. 


Postfix = NULL 
fe ee 


P4: 


Sequence: 


Prefix = 24NL 
Print 
Postfix = CR 


ZK-0665-GE 


P4: 


The set mode and set characteristics functions take the following device- 
or function-dependent arguments if no function modifiers are specified: 


¢ Pi—Address of characteristics buffer 
¢ P2—Length of characteristics buffer (default length is 8 bytes) 


e P3—Speed specifier (bits 0 through 7 = transmit; 8 through 15 = 
receive) 


e P4—Fill specifier (bits 0 through 7 = CR fill count; bits 8 through 15 = 
LF fill count) 


e P5—Parity flags 
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Note: 


The Pl argument points to a variable length block, as shown in 
Figure 8-7. With the exception of terminal characteristics, the contents 
of the block are the same for both the set mode and set characteristics 
functions. 


Figure 8-7 Set Mode and Set Characteristics Buffers 


31 24 23 16 15 87 0 


Page Length Basic Terminal Characteristics 





P2 = 8 (Default) 


31 24 23 16 15 87 0 


Page Length Basic Terminal Characteristics 





Extended Terminal Characteristics 


P2=12 


ZK-0691-—GE 


In the buffer, the device class is DC$_TERM, which is defined by the 
$DCDEF macro. The terminal type is defined by the $TTDEF macro, 
for example, TT$_LA86. The page width is a value in the range of 1 
through 511. The page length is a value in the range of 0 through 255. 
Table 8—5 lists the values for terminal characteristics. Table 8-6 lists the 
extended terminal characteristics. Characteristics values are defined by 
the $TTDEF and $TT2DEF macros. 


Make sure that the selected device is a terminal before performing 
any set mode function, particularly when using SYS$INPUT or 
SYSSOUTPUT. 


The P83 argument defines the device speed, such as TT$C_BAUD_300. The 
low eight bits specify the transmit speed, and the high eight bits specify 
the receive speed. If no receive speed is specified, the indicated transmit 
speed is used for both transmitting and receiving. If neither the transmit 
nor the receive speed is specified (P3 = 0), the baud rate is not changed. 
The terminal driver ignores the receive speed bits for interfaces that do 
not support split-speed operation. While speeds up to 19.2K baud can 

be specified, not all controllers support all speed combinations. Refer to 
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the associated hardware documentation to determine which speeds are 
supported by your controller. 


P4 contains fill counts for the carriage-return and line-feed characters. 
Bits 0 through 7 specify the number of fill characters used after a carriage 
return. Bits 8 through 15 specify the number of fill characters used after a 
line feed. 


P4 is applicable only if TT$M_CRFILL or TT$M_LFFILL is specified as a 
terminal characteristic for the current QIO request; see Table 8—5. 


Several parity flags can be specified in the P5 argument: 


¢ TT$M_ALTRPAR—Alter parity. If set, check the state of 
TT$M_PARITY and TT$M_ODD and, if indicated, change the parity. 
Otherwise, ignore these bits. TT$M_ALTRPAR is not supported for 
LAT devices. 


¢ TT$M_PARITY—Enable parity on terminal line if set, disable if clear. 
e TT$M_ODD—Parity is odd if set. 


¢ TT$M_ALTDISPAR—Alter dismiss parity errors. If set, check the 
state of TT$M_DISPARERR. 


¢ TT$M_DISPARERR—Dismiss parity errors. If this mode is set, 
input errors with a parity error flagged are discarded and no error 
is reported. 


Note: If parity is enabled, the DZ11 generates a parity check bit to 
detect parity mismatch. Unless TT$M_DISPARERR is enabled, 
parity errors that occur during an I/O read operation are fatal 
to the operation. Parity errors that occur on input characters 
(that is, keys pressed on the keyboard) when no I/O operation 
is in progress might result in a character loss. 


¢ TT$M_BREAK—Generate a break if set. The break is in effect until 
this bit is turned off. TT$M_BREAK is supported by the LTDRIVER 
for terminal servers that support the break capability, such as the 
DECserver 200 and DECserver 500. However, in the case of LAT 
terminals, the terminal server controls the duration of the break. 


e TT$M_ALTFRAME—If set, the four low-order bits of P5 become 
the frame size. Note that the frame size is for data bits only and 
is exclusive of parity. TT$M_ALTFRAME is not supported for LAT 
devices. 


To take the existing parity settings, modify them, and use them in the set 
mode or set characteristic function, move the byte starting at the second 
nibble of the buffer that is going to be used in the P5 argument. For 
example, the following instructions change the parity from even to odd: 


insv losb+6, #4, #8, flags 
bisl #ttSm_altrpar!tt$m_odd!tt$m_parity, flags 


The following instruction then resets the parity to its original state: 


bicl #tt$m_odd!tt$m_parity, flags 
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Note: 


Note: 


See Section 8.2.5 for information about the SET TERMINAL/FRAME 
command. 


Application programs that change terminal characteristics should perform 
the following steps: 


1 Use the I0O$_SENSEMODE function to read the current 
characteristics. 


Modify the characteristics. 
3 Use the set mode function to write back the results. 


4 Ifthe characteristic is intended to be reset when the image exits, the 
application must perform this operation. 


Failure to follow this sequence will result in clearing any previously set 
characteristic. 


Two stop bits are used only for data rates less than or equal to 150 baud; 
higher data rates default to one stop bit. 


The set mode and set characteristics functions can take the enable 
CTRL/C AST, enable CTRL/Y AST, enable out-of-band AST, hangup, set 
modem, broadcast, and loopback function modifiers that are described in 
the next several sections. 


If an attempt is made to turn on TT2$V_FALLBACK for a 
disconnected virtual terminal (_VTAx:) or if the Terminal Fallback 
Facility has not been activated, the status code SS$_BADPARAM 
will be returned. For more information on TFF, refer to the VMS 
Terminal Fallback Utility Manual. 


8.4.3.1 Hangup Function Modifier 


The hangup function disconnects a terminal that is on a dial-up line. 
(Dial-up lines are described in Section 8.2.3.) The following combinations 
of function code and modifier are provided: 


¢ JO$_SETMODE!IO$¢M_HANGUP 
¢ IO$_SETCHAR!IIO$M_HANGUP 


The hangup function modifier takes no arguments. SS$_NORMAL is 
returned in the I/O status block. 


For remote terminals, the hangup function breaks the network 
connection to the local system ending the remote terminal session. 


8.4.3.2 Enable CTRL/C AST and Enable CTRL/Y AST Function Modifiers 


Both set mode functions can take the enable CTRL/C AST and enable 
CTRL/Y AST function modifiers. These function modifiers request the 
terminal driver to queue an AST for the requesting process when you 
press CTRL/C or CTRL/Y. The following combinations of function code and 
modifier are provided: 


¢ I0$_SETMODE!IO$M_CTRLCAST—Enable CTRL/C AST 
¢ IO$_SETMODE!IO$M_CTRLYAST—Enable CTRL/Y AST 
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These function code modifier pairs take the following device- or function- 
dependent arguments: 


e Pi—Address of the AST service or 0 if the corresponding AST is 
disabled 


¢ P2—AST parameter 


e P38—Access mode to deliver AST (maximized with caller’s access mode) 


If the respective enabling is in effect, pressing CTRL/C or CTRL/Y gains 
the attention of the enabling process (see Table 8—2). 


Enable CTRL/C and CTRL/Y AST are one-time enabling function 
modifiers. After the AST occurs, it must be explicitly reenabled by one 

of the two function code combinations before an AST can occur again. This 
function code is also used to disable the AST. The function is subject to 
AST quotas. 


You can have more than one CTRL/C or CTRL/Y enabled; pressing 
CTRL/C, for example, results in the delivery of all CTRL/C ASTs. ASTs 
are queued and delivered to the user process on a first-in/first-out basis 
for each access mode. However, ASTs are processed in the reverse order 
of the CTRL/C AST or CTRL/Y AST requests that have been issued to the 
terminal driver (on a last-in/first-out basis). 


If no enable CTRL/C AST is present, the holder of an enable CTRL/Y 
AST receives an AST when CTRL/C is pressed; carriage-return/line-feed 
combination, “Y, and RETURN are echoed. 


Figure 8-9 shows the relationship of CTRL/C and CTRL/Y with the out-of- 
band function. If CTRL/C or CTRL/Y is an enabled out-of-band character, 
any out-of-band ASTs specified for this character are delivered. If the 
IO$M_INCLUDE function modifier is included in the out-of-band AST 
request for this character, an enabled CTRL/C or CTRL/Y AST is also 
delivered. . 


Enable CTRL/C AST requests are flushed by the Cancel I/O on Channel 
($CANCEL) system service. Enable CTRL/Y AST requests are flushed by 
the Deassign I/O Channel ($DASSGN) system service. 


CTRL/Y is normally used to gain the attention of the command interpreter 
and to input special commands such as DEBUG, STOP, and CONTINUE. 
Programs that are run from a command interpreter should not enable 
CTRL/Y. Because ASTs are delivered on a first-in/first-out basis, the 
command interpreter’s AST routine gets control first, and might not allow 
the program’s AST to be delivered at all. Programs that require the use of 
CTRL/Y should use the LIBSDISABLE_CTRL RTL routine to disable DCL 
recognition of CTRL/Y. 


Section 8.2.1.2 describes other effects of CTRL/C and CTRL/Y. 
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8.4.3.3 Set Modem Function Modifier 


Note I: 


Note 2: 


The set modem function modifier is used in maintenance operations to 
allow a process to activate and deactivate modem control signals. Both set 
mode and set characteristics functions can take the set modem function 
modifier. The following combinations of function code and modifier are 
provided: 


e I0$_SETMODE!IO$M_SET_MODEM!IO$M_MAINT 
¢ I0$_SETCHAR!IIO$M_SET_MODEM!IO$M_MAINT 


These function code modifier pairs take the following device- or function- 
dependent argument: ; 


¢ P1—The address of a quadword block that specifies which modem 
control signals to activate or deactivate 


Figure 8-8 shows the format of this block. 
Figure 8-8 Set Mode P1 Block 
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The modem on and modem off fields, in combination or separately, can 
specify one or more of the following values: 


¢ TT$M_DS_RTS—Request to send (RTS) 
¢ TT$M_DS_DTR—Data terminal ready (DTR) 
¢ TT$M_DS_SECTX—Transmitted backward channel data (Sec Txd) 


The $TTDEF macro defines which of these values the modem on and 
modem off fields specify. These values can only be specified if the terminal 
characteristic TT$M_MODEM is not set. Otherwise, an error (SS$_ 
ABORT) will result. 


The set modem function is not supported for remote terminals. 
The status SS$_DEVREQERR is returned in the I/O status block. 


Because the DMF32 does not provide the secondary transmitted 
data signal (Sec Txd), the driver sets the secondary request to send 
the signal. Users should connect a jumper cable between pins 14 
and 19 on the DMF32. 
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8.4.3.4 Loopback Function Modifier 


Note: 


Note: 


Note: 


The loopback function modifier is used in maintenance operations to place 
the terminal line in a hardware loopback mode. Data transmitted to a line 
in this mode is returned as receive data. If the controller does not support 
loopback mode or the terminal line has the TT$M_MODEM characteristic 
set, an error status (SS$_ABORT) is returned. Both set mode functions 
can take the loopback function modifier. 


The loopback function is not supported for remote terminals. The 
status SS$_DEVREQERR is returned in the I/O status block. 


The following combinations of function code and modifier are provided: 
¢ I0$ SETMODE!IO$M_LOOP!IO$M_MAINT 
¢ I10$_SETCHAR!IO$M_LOOP!IO$M_MAINT 


Data transmitted in the loopback mode should only be written in records 
less than or equal to the size of the type-ahead buffer (see Section 8.2.1.5). 
Programs that use the loopback function modifier should incorporate a 
one-second delay to allow the controller to enable the loopback mode after 
the request is posted. Write requests should also include the 
I0$M_NOFORMAT function modifier to prevent the terminal driver from 
formatting input or output data. 


The serial line interfaces for the VAX 8200 processor implement 
an internal loopback bus that is common to all four serial lines. 
The hardware allows all serial lines operating in loopback mode to 
transmit data to the bus at the same time. If more than one serial 
line writes data to the bus, all of the transmitted data is combined. 
and made available to the receiving end of those same serial lines. 
Thus, the received data may be different from the transmitted data 
if more than one serial line is operating in loopback mode at the 
same time. To prevent receiving such spurious data, you must not 
operate multiple serial lines in loopback mode. 


The VMS operating system provides another function modifier to reset 
a terminal line previously placed in loopback mode. The following 
combinations of function code and modifier are provided: 


¢ I0$_SETMODE!IO$M_UNLOOPIIO$M_MAINT 
¢ I0$_SETCHAR!IIO$M_UNLOOP!IIO$M_MAINT 


Programs that use the unloop function modifier should incorporate a one- 
second delay to allow the controller to reset the loopback mode after the 
request is posted. 


IO$M_LOOP and IO$M_UNLOOP are not supported for LAT 
devices. 
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8.4.3.5 Enable Out-of-Band AST Function Modifier 
The enable out-of-band AST function modifier requests that the terminal 
driver queue an AST for the requesting process when you enter any one 
of 32 control characters. The following combinations of function code and 
modifier are provided: 


¢ IO$_SETMODE!IO$M_OUTBAND—Enable out-of-band AST 
¢ IO$_SETCHARITIO$M_OUTBAND—Enable out-of-band AST 


These function code modifier pairs take the following device- or function- 
dependent arguments: 


¢ P1—Address of the AST service or 0 if the AST entered on this | 
channel is to be canceled. (The AST parameter will be the out-of-band 
character.) 


e P2—Address of a character mask with the same format as the short 
form terminator mask (see Section 8.4.1.2). 


e P3—Access mode to deliver AST (maximized with the caller’s access 
mode). 


The IO$_SETMODE!IO$M_OUTBAND function can optionally take the 
following function modifiers: 


¢ IO$M_INCLUDE—Include the character typed in the data stream. 


¢ IO$M_TT_ABORT—Allow current read and write operations to be 
aborted. (The IOSB for aborted operations returns the status 
SS$_CONTROLC.) 


If an out-of-band AST is in effect, pressing any control character specified 
in the P2 mask gains the attention of the enabling process. Figure 8-9 
shows the relationship of the out-of-band function with some of the control 
characters. 


You can have only one out-of-band AST enabled per channel. 


Out-of-band ASTs are repeating ASTs; they continue to be delivered until 
specifically disabled. Out-of-band AST enables are flushed by the Cancel 
1/O on Channel ($CANCEL) system service. 


8.4.3.6 Broadcast Function Modifier 
The broadcast function modifier allows you to turn on or turn off selected 
broadcast requester identifiers (IDs). The following combination of 
function code and modifier is provided: . 


¢ JO$ SETMODE!IO$M_BRDCST 
This function code modifier pair takes the following device- or function- 
dependent arguments: 


¢ P1—A buffer that contains the bits that specify the requester IDs to be 
broadcast 
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Figure 8-9 Relationship of Out-of-Band Function with Control Characters 
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e P2—The length of the P1 buffer (default is eight bytes) 


The first longword of P1 is reserved for use by Digital facilities, as shown 
in Table 8-12. The symbols are defined in the system macro library 
($BRKDEF). The second longword is for customer use to specify selected 
bits. If any bit is set in the Pl buffer, that particular requester ID is 
turned off for broadcast. 


Table 8-12 Broadcast Requester IDs 
Bit Meaning 


BRK$C_DCL Disables broadcasts by CTRL/T 


BRK$C_GENERAL Disables broadcasts by the DCL command REPLY and the 
SYS$BRDCST system service 


BRK$C_MAIL Disables broadcasts by the Mail Utility 

BRK$C_PHONE Disables broadcasts by the Phone Utility 

BRC$C_QUEUE Disables broadcasts about batch and print queues 

BRK$C_SHUTDOWN Disables broadcasts about system shutdown 

BRK$C_URGENT Disables broadcasts labeled URGENT by the REPLY 
command 

BRK$C_USERn Disables broadcasts by images associated with the specified 


value; n can be any decimal integer between 1 and 16 


8.4.4 LAT Port Driver QIO Interface 


The LAT (Local Area Transport) port driver accommodates I/O requests 
from application programs for connections to remote devices on one or 
more terminal servers, and I/O requests that support other miscellaneous 
functions. A remote device, such as a printer, can be shared in a LAT 
configuration. Before an application program can access a remote 
device, the VMS system manager must create logical devices on the VMS 
operating system and map them to physical devices connected to terminal 
servers. Creating and mapping these logical devices can be done either 
with the LAT Control Program (LATCP) Utility or with a $QIO request 
from a program that has PHYS_IO privilege. Once mapped, application 
programs can establish and terminate connections to these remote devices. 


This section describes the QIO interface to the LAT port driver 
(LTDRIVER) and the functions and function modifiers you use to establish 
and terminate connections to remote devices. The QIO interface allows 
application programs to access and modify information contained in the 
LTDRIVER data structures and to initiate events and obtain status 
information. You must use these QIO functions to establish a connection 
to a remote device from an application program. Digital does not support 
any other methods of connection. 


The LTDRIVER responds to TEST SERVICE commands issued at 
terminal servers that support the TEST SERVICE command, such as 
the DECserver 200 and DECserver 500. 
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LAT devices can use all read and write function modifiers listed for the 
terminal driver function codes except those modifiers that apply to modems 
(see Sections 8.4.1 and 8.4.2). 


The VMS operating system does not support the following set mode or set 
characteristics function code modifiers for LAT devices: 


¢ 10$M_LOOP 

¢ 10$M_UNLOOP 
¢ TT$M_ALTRPAR 
¢ TT$M_ALTFRAME 
¢ TT$M_MODEM 

¢ TT$M_READSYNC 
¢ TT2$M_SETSPEED 


With LAT devices, the terminal server, rather than the VMS host, handles 
flow control to the physical device. A separate flow control mechanism 
exists between the server and the host. 


8.4.4.1. LAT Port Driver Functions 
The VMS operating system provides the following combinations of function 
code and modifier: 


¢ JO$_TTY_PORT!IIO$M_LT_CONNECT—Requests the LAT port driver 
make a connection to a remote device on a server. 


¢ I0$_TTY_PORT!IO$M_LT_DISCON—Requests the LAT port driver 
terminate the LAT connection to the remote device. 


¢ I0O$ TTY_PORT!IO$M_LT_MAP_PORT—Associates a specific port 
on a terminal server with a LAT (LTAxxx:) device. Equivalent 
to the LATCP command SET PORT LTAxxxx:/NODE=server-name 
/PORT=port-name. 


¢ I0$ TTY_PORT!IO$M_LT_RATING—Sets a static rating for a VMS 
service. This QIO is equivalent to the LATCP command 
SET SERVICE/STATIC_RATING=n. 


The LAT port driver can only connect to a remote device if it is currently 
not in use. Table 8-13 lists the conditions that can occur when an 
application program issues an IO$M_LT_CONNECT request for a 
connection to a remote device. After a request for a connection is 
queued on the terminal server, the QIO request is not completed until 
the connection is established, rejected, or timed out. 
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Table 8-13 IO$M_LT_CONNECT Request Status 


Event 


Connection established 


Connection timeout 


Connection rejected 


Connection request 
invalid 


Connection already 
established on port 


IOSB Status 
SS$_NORMAL 


SS$_TIMEOUT 


SS$_ABORT. 
IOSB+2 contains 
LAT rejection code. 


No status. 
SS$_ILLIOFUNC 
returned in Register 
0. 


No status. 
SS$_DEVACTIVE 
returned in Register 
0. 


Explanation 


The connection is successful, and 
the device is ready to use. 


The connection timed out. The 
server is not available, or an 
incorrect server name was 
specified. The timeout period 
is 5 seconds. 


The connection cannot be made. 
See Table 8-14 for possible 
reasons. The LAT port driver 
updates the I/O status block. 


The QIO request is not to an 
applications port. The LAT 
port driver rejects the request 
immediately. 


The QIO request is for an 
applications port already in use. 
The LAT port driver rejects the 
request immediately. 


After you enter a disconnect request (IO$_TTY_PORT!IO$M_LT_ 
DISCON), the applications port’s UCB goes off line momentarily. A 
connect request (IO$_TTY_PORT!IIO$M_LT_CONNECT) may return a 
SS$_DEVACTIVE status if the connect request was immediately preceded 
by a disconnect request. In this case, reenter the connect request. 


The IO$M_LT_MAP_PORT modifier accepts two arguments: P1 and P2. 
P1 is the address of an item list, which must contain the node name, and 
either the port name or the service name of the remote terminal server 
port. (These names must be defined locally on the terminal server.) The 
item list can also contain the VMS link name and the terminal server 
Ethernet address. The item list, which must be in type 3 format (see 
Figure 8-10), is terminated by a longword of 0. The item list contains the 


following parameters: 


¢ IO$V_LT_MAP_NODNAM—tThe node name. The node name is the 
name of the terminal server where the application device is located. 


e JO$V_LT_MAP_PORNAM—tThe port name. 
e IO$V_LT_MAP_SRVNAM—The service name. 
e JO$V_LT_MAP_LNKNAM—tThe Ethernet link name, which is always 


required, 


¢ JO$V_LT_MAP_NETADR—The address of the 6-byte word containing 
the Ethernet address of the terminal server. IO$V_LT_MAP_NETADR 
can be substituted for IO$V_LT_MAP_ NODNAM. 
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Figure 8-10 IO$M_LT_MAP_PORT Item List 
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The P2 argument for IO$M_LT_MAP_PORT is a longword that passes 
queued status. Bit 0 cleared means nonqueued; bit 0 set means queued. 


The 10$M_LT_ RATING modifier accepts two arguments: Pl and P2. P1 is 
the address of the string descriptor that contains the service name, which 


must already exist. P2 is the rating to assign the service. Ratings range 
from 0 to 255 (decimal). 


Table 8-14 lists the possible status of the I/O Status Block after a 
IO$M_LT_MAP_PORT or IO$M_LT_RATING request. 

Table 8-14 lIO$M_LT_MAP_PORT and IO$M_LT_RATING Request Status 
Event Contents of I/O Status Block and RO 


Operation successful SS$_NORMAL 


Illegal or incomplete parameter list; SS$_BADPARAM 
non-existent service 


Access violation in one of the SS$_ACCVIO 
arguments 
No privilege SS$_NOPRIV 


8.4.4.2 Application Services Creation 
Rather than the normal timesharing service offered by the VMS operating 
system, VMS application programs can make use of LAT application 
services that allow terminal server users to connect to a specialized 
application. To do this, the system manager must create LAT ports that 
are dedicated to a particular application service. When a terminal server 
user uses the terminal server CONNECT command to connect to an 
application service, the connection is directly to the VMS application 
program that controls a LAT port (LTA device) associated with that 
service. In this case the VMS prompt Username: is not received. Digital 
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recommends that you create application services for VMS service nodes in 
the following order: 


1 Define the dedicated ports in LTLOAD.COM and execute the command 
procedure in SYSTARTUP_V5.COM. (Refer to the VMS LAT Control 
Program (LATCP) Manual and Guide to Setting Up a VMS System for 
additional information.) 


2 Run the application program. Within the application program 
allocate dedicated ports with the same name as those defined in 
LTLOAD.COM. Use the Assign I/O Channel ($ASSIGN) system service 
to assign service channels to the ports. 


3 Post a read request to the dedicated ports. When the terminal user 
connects to the service and presses the Return key, the application 
program can perform I/O to the dedicated port. 


4 ‘To break the connection, use the Deassign I/O Channel (SDASSGN) 
system service to deassign the channel and the Deallocate Device 
($DALLOC) system service to deallocate the device. The application 
program must reallocate the port and reassign the channel in 
preparation for the next connection. 


An example of the application service concept is a VMS program that 
provides the time of day. For this example, the system manager includes 
the following lines in LTLOAD.COM (or enters them manually in the 
LATCP program): 


CREATE SERVICE TIME/ID="At the tone, the time will be" 
CREATE PORT LTA99:/DEDICATED 
SET PORT LTA99:/DEDICATED/SERVICE=TIME 


An application program then assigns a channel to device LTA99. When 
a terminal server user types CONNECT TIME, the user is connected to 
this application program, and the program prints out the time of day. The 
program then deassigns the channel, which disconnects the server user. 


A system manager may associate more than one LAT port with the same 
service. In that case, the application program that offers the service 
should assign channels to all of the LTA devices created for that service. 


8.4.4.3. Hangup Notification 
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To allow notification by the terminal driver of abnormal termination 
during write operations, you should enable a CTRL/Y AST on the channel 
(see Section 8.4.3.2). This ensures that the terminal driver notifies 
application programs, which are writing data, of an abnormal connection 
termination. Note that the VMS operating system does not return an AST 
parameter to the CTRL/Y AST routine. 


When an application program with a pending read request has an 
abnormal LAT connection termination, the VMS terminal driver returns a 
SS$_HANGUP status in the first word of the IOSB. 
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8.4.5 | Sense Mode and Sense Characteristics 


The sense mode and sense characteristics functions sense the 
characteristics of the terminal and return them to the caller in the I/O 
status block. The following function codes are provided: 


e I0$_SENSEMODE 


¢ IO$_SENSECHAR 

I10$_SENSEMODE returns the temporary characteristics of the terminal 
(the characteristics associated with the current process), and IO$_ 
SENSECHAR returns the permanent characteristics of the terminal. 
10$_SENSEMODE is a logical I/O function and requires no privilege. 


10$_SENSECHAR is a physical I/O function and requires the privilege 
necessary to perform physical I/O. 


These function codes take the following device- or function-dependent 
arguments: 


e Pi—dAddress of a characteristics buffer 
e P2—Length of characteristics buffer (default length is 8 bytes) 


For remote terminals, specify a P2 value of 8 or 12 only. 


The Pl argument points to a variable-length block, as shown in 
Figure 8-11. 


Figure 8-11 Sense Mode Characteristics Buffer 
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In the buffer, the device class is DC$_TERM, which is defined by the 
$DCDEF macro. The terminal type is defined by the $TTDEF macro, such 
as TT$_LA36. The maximum entry for buffer size (page width) is 255. 
Table 8—5 lists the values for terminal characteristics. Table 8—6 lists the 


extended terminal characteristics. Characteristics values are defined by 
the $TTDEF macro. 


The sense mode and sense characteristics functions can take the type- 
ahead count, read modem, and broadcast function modifiers described in 
the next few sections. 
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8.4.5.1 Type-ahead Count Function Modifier 
The type-ahead count function modifier returns the count of characters 
presently in the type-ahead buffer and a copy of the first character in the 
buffer. In this case, the P1 argument points to a characteristics buffer 
returned by IO$M_TYPEAHDCNT. Figure 8-12 shows the format of this 
buffer. 


Figure 8-12 Sense Mode Characteristics Buffer (type-ahead) 
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8.4.5.2 Read Modem Function Modifier 
The read modem function modifier allows access to controller-dependent 
information. The following combinations of function code and modifier are 
provided: 


e IO$_SENSEMODE!IO$M_RD_MODEM 
¢ IO$_SENSECHAR!IIO$M_RD_MODEM 


These function code modifier pairs take the following device- or function- 
dependent argument: 


¢ Pi—The address of a quadword block 


Figure 8-13 shows the format of this block. 
Figure 8-13 Sense Mode P1 Block 
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The receive modem field returns the value of the current input modem 
signals. Any or all of the following signals can be returned: 


¢ TT$M_DS_DSR—Data set ready (DSR) 
¢ TT$M_DS_RING—Calling indicator (RING) 


¢ TT$M_DS_CARRIER—Data channel received line signal detector 
(CARRIER) 


¢ TT$M_DS_CTS—Ready for sending (CTS) 
e TT$M_DS_SECREC—Received backward channel data (Sec RxD) 


The $TTDEF macro defines the symbols for the receive modem field. 


The controller type field returns the type of terminal controller in use 
by the currently active terminal line. The $DCDEF macro defines the 
symbols for the following types of controllers: 


¢ DT$_DZ11—DZ11 and DZV11 
¢ DT$_DZ32—DZ32 

e DT$ DMF32—DMF32 

¢ DT$_DMB32—DMB32 

¢ DT$_DMZ32—DMZ32 

¢ DT$ DHV—DHV11 

¢ DT$ DHU—DHU11 

¢ DT$_LAT—LAT server 


Note 1: The IO$M_RD_MODEM function modifier is not supported for LAT 
devices. 


Note 2: The IO$M_RD_MODEM function modifier is not supported for 
remote terminals. The status SS$_DEVREQERR is returned in the 
V/O status block. 


8.4.5.3 Broadcast Function Modifier 
The broadcast function modifier returns those bits that have been set 
by the set mode function modifier IO$M_BRDCST (see Table 8-12 in 
Section 8.4.3.6). The following combination of function code and modifier 
is provided: 


¢ IO$_SENSEMODE!IO$M_BRDCST 
This function code modifier pair takes the following device- or function- 
dependent arguments: 


e P1—A buffer that contains the bits that specify the requester [Ds to 
be broadcast. (If the bit is set in the first longword, that particular 
command is turned off for broadcast.) 


e P2—The length of the P1 buffer. 
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The I/O status block (IOSB) formats for the read, write, set mode, set 
characteristics, sense mode, sense characteristics, and LAT port driver I/O 
functions are shown in Figures 8-14, 8-16, 8-17, and 8-18. Figure 8-15 
shows the IOSB format for the itemlist read function. Appendix A lists 
the status returns for these functions. (The VMS System Messages 

and Recovery Procedures Reference Manual provides explanations and 
suggested user actions for these returns.) 


Figure 8-14 IOSB Contents—Read Function 


+2 lOSB 


+6 +4 
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Figure 8-15 IOSB Contents—lItemlist Read Function 


Cursor Position} Terminator Terminator 
from EOL Length (Reserved) Character 





IOSB Contents: Itemlist Read Function 
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Figure 8-16 lOSB Contents—Write Function 





IOSB Contents: Write Function 
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Figure 8-17 IOSB Contents—Set Mode, Set Characteristics, Sense 
Mode, and Sense Characteristics Functions 


Receive Speed *| Transmit Speed Status 





a Parity Flags LF Fill Count | CR Fill Count 


* Only specified if different than transmit speed. 
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In Figure 8-14, the offset to terminator at IOSB+2 is the count of 
characters before the terminator character (see Section 8.4.1.2). The 
terminator character is in the buffer at the offset specified in IOSB+2. 
When the buffer is full, the offset at IOSB+2 is equal to the requested 
buffer size. At the same time, IOSB+4 is equal to 0. In the case 

of multiple character escape sequences that act as terminators, the 
terminator at IOSB+4 is the first character (ESC) of the escape sequence. 
IOSB+6 contains the size of the terminator string, usually 1. However, 
in an escape sequence, IOSB+6 contains the size of the validated escape 
sequence (see Section 8.2.1.4). The sum of IOSB+2 and IOSB+6 is the 
number of characters in the buffer. 


In Figure 8-15 the terminator position word contains a number, the 
character of which is determined by the mode of operation. For itemlist 
read operations that do not specify TRM$K_EM_RDVERIFY, this word 
contains the number of characters from the end of the buffer to the cursor 
location at the time the terminator character was received. If TRM$K_ 
EM_RDVERIFY is specified, the terminator position word contains the 
offset into the buffer from the nonverified character. 


The byte at IOSB+5 passes the status information listed in Table 8-15 on 
TRM$K_EM_RDVERIFY operations in which TRM$M_TM_ARROWS or 
TRM$M_TM_TOGGLE is set in TRM$ MODIFIERS. 
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Table 8-15 Byte IOSB+5 Status Information 


Bit Interpretation 

7 (sign bit) 0 to indicate rest of bits valid. This applies to 
insert/overstrike and arrow key read verify functionality 
only. 

6-2 Always 0 if bit 7 is equal to 0. Not used; reserved for 
future use. 


1 TRM$V_ST_OTHERWAY Set to indicate that read is terminated in left-justify 
insert mode or right-justify overstrike mode. 


0 TRM$V_ST_FIELD_FULL Read terminated on an auto-iab field full condition. 
1OSB+7 contains an index to the cursor. 


In Figure 8-16, the remote terminal driver does not return the number of 
lines output or the cursor position. 


When an application program makes an I/O request for a connection to 

a remote device on a terminal server, the LAT port driver places status 

information about the request into the first word of the I/O status block, 
as shown in Figure 8-18. Tables 8-13 and 8-14 list the possible status 

returns. 


If the server rejects the request, the LAT port driver returns a numeric 
LAT rejection code in the second word of the I/O status block. Table 8-16 
lists the LAT rejection codes. 


Figure 8-18 IOSB Contents—LAT Port Driver Function 





+2 0 


(Reserved) (Reserved) 
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Table 8-16 LAT Rejection Codes 


Value Reason 


0 Unknown. 

2 System shutdown in progress. 
5 Insufficient resources at server. 
6 Port or service in use. 


(continued on next page) 
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Table 8-16 (Cont.) LAT Rejection Codes 


Value Reason 


No such service. 
Service is disabled. 


fo) Service is not offered on the requested port. 
10 Port name is unknown. 
LS Immediate access rejected. 
14 Access denied. 
15 Corrupted request. 
16 Requested function is not supported. 
17 Session cannot be started. 
18 Queue entry deleted by server. 
19 Illegal request parameters. 
8.6 Terminal Driver Programming Examples 


This section contains the following programming examples: 


¢ Example 8-1 shows several I/O operations using the full-duplex 
capabilities of the terminal. 


¢ Example 8-2 shows a typical read verify operation. 


e Example 8-3 shows how to connect to an applications (LT) device. 


8.6.1. Terminal I/O Program Example 


Example 8—1 illustrates some important concepts about terminal driver 
programming: assigning an I/O channel, performing full-duplex I/O 
operations, enabling CTRL/C AST requests, and itemlist read operations. 
The program is designed to run with a terminal set to full-duplex mode. 
The initialization code queues a read request to the terminal and enables 
CTRL/C AST requests. The main loop then prints out a random message 
every three seconds. When you enter a message on the terminal, the read 
AST routine prints an acknowledgment message and queues another read 
request. If you press CTRL/C, the associated AST routine cancels the I/O 
operation on the assigned channel and exits to the command interpreter. 
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Example 8-1 Terminal Program Example 





-TITLE FULL DUPLEX TERMINAL PROGRAMMING EXAMPLE 
-IDENT /05/ 


KKKKKKEKRKKKKKEKKKKK KK KKK KKEKKKKKKKKKKEKKKKEKKKKKEKKKEKKKKKKKKKKEKKRKKKKKKKEKE 


; TERMINAL PROGRAM 
FOR RR IO I RRR RK A KKK KKK KK KKK RAK KR KK KK RK KK KERR AKER KKK KKK EKA 


.-SBTTL DECLARATIONS 
. DISABLE GLOBAL 


; Declare the external symbols and MACRO libraries. 


. EXTERNAL LIBSGET_EF 
. LIBRARY ’ SYSSLIBRARY: LIB.MLB’ 
. LIBRARY ’ SYSSLIBRARY: STARLET .MLB’ 


; Define symbols 


SIODEF ; Define I/O function codes 

SQIODEF ; Define QIO definition codes 

SSSDEF ; Define the system service status codes 
STRMDEF ; Define itemlist read codes 

STTDEF ; Terminal characteristic definitions 


; Define macros 


- SHOW 
-MACRO ITEM LEN=0, CODE, VALUE 
- WORD LEN 


.WORD TRMS 'CODE’ 
.LONG VALUE 


- LONG 0 
- ENDM ITEM 
- NOSHOW 


; Declare exit handler control block 


EXIT HANDLER BLOCK: 


. LONG 0 ; System uses this for pointer 

. LONG EXIT HANDLER ; Address of exit handler 

. LONG aL ; Argument count for handler 

. LONG STATUS ; Destination of status code 
STATUS: .BLKL 1 ; Status code from SEXIT 


; Allocate terminal descriptor and channel number storage 
TT_DESC: 

-ASCID /SYSSINPUT/ ; Logical name of terminal 
TT CHAN: 

. BLKW 1 ; TT channel number storage 
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; Define acknowledgment message. This is done right above input buffer 
; so that we can concatenate the two together when the acknowledgment 
7 message is issued. 
ACK MSG: 

-ASCII <CR><LF>/Following input acknowledged: / 
ACK_MSGLEN=.-ACK_MSG ; Calculate length of message 
; Allocate input buffer 


. 
, 


IN_BUFLEN = 20 ; Set length of buffer 
IN BUF: 

. BLKB IN_BUFLEN ; Allocate character buffer 
IN_IOSB: 

. BLKQ 1 ; Input I/O status block 


; Define out-of-band ast character mask 
CNTRLA_ MASK: 
. LONG 0 
. LONG “B0010 ; Control A mask 


° 
’ 


; Define old terminal characteristics buffer 


? 
OLDCHAR_BUF_LEN = 12 
OLDCHAR_BUF: 

. BLKB OLDCHAR_ BUF_LEN 


e 
7 


; Define new terminal characteristics buffer 
NEWCHAR BUF LEN = 12 


NEWCHAR BUF: 
.BLKB NEWCHAR BUF_LEN 


; Define carriage control symbols 


CR=*X0D ; Carriage return 
LF=*X0A ; Line feed 


; Define output messages 


; Output messages are accessed by indexing into a table of 
; longwords with each message described by a message address and 
7 message length 
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ARRAY: ; Table of message addresses and 
; lengths 
. LONG 10$ ; First message address 
. LONG 15$ ; First message length 
. LONG 20$ 
. LONG 25$ 
. LONG 30$ 
. LONG 35$ 
. LONG 40$ 
- LONG 45$ 


; 
; Define messages 


° 
v 


10$: -ASCII <CR><LF>/RED ALERT!!! RED ALERT! !!/ 
15$=.-105 

208: -ASCII <CR><LF>/ALL SYSTEMS GO/ 

258=.-208 

’ 

308: -ASCII <CR><LF>/WARNING..... INTRUDER ALARM/ 
35$=.-30$ 

40S: -ASCII <CR><LF>/***** SYSTEM OVERLOAD *****/ 


45$=.-40$ 
* Static QIO packet for message output using QIO$ G form 
WRITE QIO: 
SQIO EFN=SYNC_EFN, - ; QTO packet 
FUNC=10$_WRITEVBLK! IO$M_BREAKTHRU! IOSM_REFRESH, - 
IOSB=SYNC_IOSB 


; Declare the required I/O status blocks. 
SYNC_IOSB:: -BLKQ 1 ; I/O status block for synchronous terminal processing. 


e 
, 


; Declare the required event flags. 


ASYNC_EFN:: - BLKL 1 ; Event flag for asynchronous terminal processing. 
SYNC_EFN == WRITE QIO + 4 ; Event flag for sync terminal processing. 
TIMER_EFN:: . BLKL 1 ; Event flag for timer processing. 


Timer storage 


we Ne Ne 


WAITIME: 
. LONG -10*1000*1000*3,-1 ; 3 second delta time 
TIME: 
-BLKQ 1 ; Current storage time used for 
+ random number 
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- PAGE 
- SBITL 


START - MAIN ROUTINE 


-ENABLE LOCAL BLOCK 


ptt 


. 
, 


; Functional description: 


Start program 


KKKEKKKEKKKKKEKKKEKKKKKKKKREKKEKKKEKKKKKKEKKKEKKERKKKKKKRKKEKKKRKKKKKKKEKEKKKKKKKK 


KEKKKKKKKKKKKKKKEKKEKKKKEKEKKKKKKKKEKKEKKKKRKKKEKKKKERKEKKEKKRKEKEKRKKKKREKKKKKKKEKK 


; The following code performs initialization functions. 

; It is assumed that the terminal is already in 

; FULL-DUPLEX mode. 

; NOTE: When doing QIO_S calls, parameters Pl and P3-P6 should be 
; passed by value, while P2 should be passed by reference. 


; Input parameters: 


? None 


7 Output parameters: 


Get EFN for async terminal operations. 
Error - branch. 


Get EFN for sync terminal operations. 
Error - branch. 


Get EFN for timer operations. 
Error -— branch. 


characteristics. 


Assign terminal channel using 
logical name and channel number 
Error - branch. 

Change the characteristics of 
terminal 

Allow CTRL/C traps 

Enable CTRL/A out-of-band AST 
Queue read 

Insert channel into 

static QIO packet 


; None 
-ENTRY START “M < > 
? Get the required event flags. 
PUSHAL ASYNC_EFN 
CALLS 2-1 GS LIBSGET_EF ; 
BLBC RO, 10$ ; 
PUSHAL SYNC_EFN 
CALLS # 1, G* LIBSGET_EF ; 
BLBC RO, 10S ; 
PUSHAL TIMER_EFN 
CALLS # 1, G% LIBSGET_EF ; 
BLBC RO, 10$ ; 
: Initialize the terminal 
SASSIGN_S DEVNAM=TT_DESC, ~; 
CHAN=TT_CHAN ; 
BLBC RO, 10$ ; 
BSBW CHANGE CHARACTERISTICS ; 
BSBW ENABLE CTRLCAST ; 
BSBW ENABLE OUTBANDAST ; 
BSBW ENABLE READ ; 
MOVZWL TT CHAN, WRITE _QIO+8 ; 
BRB LOOP ; 
108: 
BRW ERROR 
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. 
, 


; This loop outputs a message based on a random number and then 


7; Gelays for 3 seconds 


. 
7 


Get random time 

Error —- branch. 

Load random bits into switch 
Load message address 

and size into QIO 

packet 


data area 


QIO error - branch. 
Get the terminal driver status. 
Terminal driver error - branch. 


message 


Timer service 

will set event flag 
in 3 seconds 

Error - branch. 
Wait for event flag 
No error if set 
Error - branch. 


-SBTTL CHANGE CHARACTERISTICS ~ CHANGE CHARACTERISTICS OF TERMINAL 


LOOP : 
SGETTIM_S TIMADR=TIME ; 
BLBC RO, 10S ; 
EXTZV #6, #2, TIME, RO ; 
MOVQ ARRAY[RO], - ; 
WRITE QIO+QIO$ P1 ; 
7 Issue QIO write using packet defined in 
SQIOW_G WRITE QIO 
BLBC RO, 10S ; 
MOVZWL SYNC_IOSB, RO 7 
BLBC RO, 10$ ; 
; Delay for 3 seconds before issuing next 
; 
SSETIMR_S EFN=TIMER_EFN,- ; 
DAYTIM=WAITIME ; 
? 
BLBC RO, 10$ ; 
SWAITFR_S EFN=TIMER_EFN ; 
BLBS RO, LOOP ; 
BRB 10$ ; 
- DISABLE LOCAL BLOCK 
. PAGE 
p++ 


ry 
, 


; Functional description: 


; Routine to change the characteristics of the terminal. 


; Input parameters: 
; None 


7; Output parameters: 
; RO - status from $QIO call. 
; Rl ~- R5 destroyed 
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CHANGE CHARACTERISTICS: 
SQIOW_S EFN=SYNC EFN, - 
CHAN=TT CHAN, - 
FUNC=#10$ SENSEMODE, - 
IOSB=SYNC_IOSB, - 
P1=OLDCHAR_BUF, - 
P2=#OLDCHAR_BUF_LEN 


BLBC RO, 10$ 
MOVZWL SYNC_IOSB, RO 
BLBC RO, 10$ 


SDCLEXH_S EXIT _HANDLER_BLOCK 


~e 


Get current terminal characteristics 


Error if clear 
Get the terminal driver status. 
Error - branch 


Declare exit handler to reset 
characteristics 

Error - branch. 

Move old characteristics into 
new characteristics buffer 


Set nobroadcast bit 


Set current terminal characteristics 


QIO error - branch. 
Get the terminal driver status. 
Terminal driver error - branch. 


BLBC RO, 10$ 

MOVC3 #OLDCHAR_BUF_LEN, - 
OLDCHAR_BUF, - 
NEWCHAR_BUF 

BISL2 #TTSM_NOBRDCST, - 
NEWCHAR_BUF+4 

SQIOW_S EFN=SYNC_EFN, - 
CHAN=TT_CHAN, - 
FUNC=#10$_SETMODE, - 
IOSB=SYNC_IOSB, - 
P1=NEWCHAR_ BUF, - 
P2=#NEWCHAR_BUF_LEN 

BLBC RO, 10$ 

MOVZWL SYNC_IOSB, RO 

BLBC RO, 10$ 

RSB 

10S; 

BRW ERROR 

. PAGE 

.SBTTL ENABLE_CTRLCAST - ENABLE CTRL/C AST 

rtt 


e 
if 


; Functional description: 
; Routine to allow CTRL/C 


7 Input parameters: 
; None 


; Output parameters: 
; None 


recognition. 
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ENABLE_CTRLCAST: 
S$QIOW_S EFN=SYNC_EFN, - 
CHAN=TT_CHAN, - 
FUNC=#10$_ SETMODE!IO$M_CTRLCAST, - 
IOSB=SYNC_IOSB, - 


P1=CTRLCAST, - ; AST routine address 
P3=#3 ; User mode 
BLBC RO, 10$ ; Error - branch. 
MOVZWL SYNC_IOSB, RO + Get the terminal driver status. 
BLBC RO, 10$ ; Terminal driver error - branch. 
RSB 
10S: 
BRW ERROR 
- PAGE 
-SBTTL ENABLE OUTBANDAST - ENABLE CTRL/A AST 
ptt 


ry 
, 


; Functional description: 
; Routine to allow CNTRL/A recognition. 


+; Input parameters: 
; None 


+ Output parameters: 
; None 


ENABLE_OUTBANDAST: 

$QIOW_S EFN=SYNC_EFN, - 
CHAN=TT_CHAN, - 
FUNC=#10$ SETMODE!IOSM OUTBAND, - 
IOSB=SYNC_IOSB, - 
P1=CTRLAAST, - 
P2=#CNTRLA MASK, - 
P3=$3 

BLBC RO, 10$ 

MOVZWL SYNC_IOSB, RO 

BLBC RO, 108 

RSB 


AST routine address 

Character mask 

User mode 

QIO error - branch. 

Get the terminal driver status. 
Terminal driver error - branch. 


Ne Se Ne Ne Ne 


™“e 


108: 
BRW ERROR 
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- PAGE 
-SBTTL ENABLE READ - QUEUE A READ TO THE TERMINAL. 
ptt 


; Functional description: 
; Routine to queue a read operation to the terminal. 


; Input parameters: 
; None 

; Output parameters: 
; None 


; Define item list for itemlist read 


ITEM LST: 
ITEM 0, MODIFIERS, - 7; Convert lowercase to 
TRM$M_TM CVTLOW!TRMSM_TM NOEDIT ; upper and inhibit line 
ITEM 6, TERM,MASK_ ADDR ; editing 
; Set up terminator mask 
ITEM LEN = ; = TTEM LST 
MASK_ADDR: 
. LONG 1@*XD ; Terminator mask is <CR> 
- WORD 1@4 , end "5" 
ENABLE READ: 
$QIO_S EFN=ASYNC_EFN, - ; Must not be QIOW form or read will block 
CHAN=TT CHAN, — # process 
FUNC=#I0S READVBLK!IOSM_EXTEND, - 
IOSB=IN_IOSB, - 
ASTADR=READAST, —- ; AST routine to execute 
PI=IN_BUF, - 7 on 
P2=#IN_BUFLEN, — 
P5=#ITEM LST, - -; Itemlist read address 
P6=#ITEM LEN ; Itemlist read size 
BLBC RO, 10S ; QIO error - branch. 


+ The queued read operation will not affect write operations due 
; to the fact that breakthru has been set for the write operations. 


RSB 


108: 
BRW ERROR 





(continued on next page) 


8-67 


Terminal Driver 


8.6 Terminal Driver Programming Examples 


Example 8-1 (Cont.) Terminal Program Example 





.PAGE | 


-SBTTL READAST - AST ROUTINE FOR READ COMPLETION 


-ENABLE LOCAL BLOCK 
ptt 
; 


; Functional description: 


; AST routine to execute on read completion. 


, Input parameters: 
; None 


7; Output parameters: 


; None 
LOS: 
MOVZWL IN_IOSB, RO 
208: 
BRW ERROR 
-ENTRY READAST “M < R2, 
BLBC IN_IOSB, 108 
MOVZWL IN_IOSB+2, RO 
ADDL2 #ACK_MSGLEN, RO 
$QIO_S EFN=ASYNC_EFN, - 
CHAN=TT CHAN, — 
FUNC=#I0$ WRITEVBLK, - 
P1=ACK MSG, - 
P2=RO0 
BLBC RO, 20S 
; Process read message 


° 
, ° 


. 
v . 


BSBW ENABLE READ 

RET 

- DISABLE LOCAL BLOCK 
- PAGE 


. 
a 


e 
4 


“we Me Ne Ne Ne 


“Ne 


“Ne Se Ne 


RS, Ra, 


Get the terminal driver status 


Exit with error status. 


R5 > ; Procedure entry mask 


Terminal driver error - branch 

Get number of characters read into RO 
Add size of fixed acknowledge message 
Issue acknowledge message 

Note, ACK must be asynchronous (QIO) 
and the terminal driver write status 
is ignored (no IOSB and AST routine). 
Specify IOSB and AST routine if output 
must be displayed on the terminal. 

QIO error - branch 


7 (user-provided code to decode command inserted here) 


Queue next read 
Return to mainline loop 


-SBTTL CTRLAAST - AST ROUTINE FOR CTRL/A 
-SBTTL CTRLCAST - AST ROUTINE FOR CTRL/C 


-SBTTL ERROR —- EXIT ROUTINE 
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pbk 
’ 


; Functional description: 


; AST routine to execute when CTRL/C or CTRL/A is entered. 


; Input parameters: 
; None 


; Output parameters: 


; None 
CTRLCAST:: 
CTRLAAST:: 
. WORD “AM < > : 
MOVL #SS$ NORMAL, RO : 
ERROR: : 
SEXIT_S RO ; 
RSB 
» PAGE 


Procedure entry mask 
Put success in RO 


Exit 


-SBTTL EXIT HANDLER - EXIT HANDLER ROUTINE 


ptt 
; 


; Functional description: 


; Exit handler routine to execute when image exits. It cancels 
: any outstanding I/O on this channel and resets the terminal 
7 characteristics to their original state. 


; Input parameters: 
; None 


; Output parameters: 


; None 

7 
-ENTRY EXIT HANDLER AM< > 
SCANCEL_S CHAN=TT_CHAN ; 
SQIOW_S BFN=SYNC_EFN, - : 


CHAN=TT_CHAN, - 
FUNC=#10$_SETMODE, - 
IOSB=SYNC_IOSB, - 
P1=OLDCHAR BUF, - 
P2=#OLDCHAR_BUF_LEN 

BLBC RO, 10$ 


‘Ne 


MOVZWL SYNC_IOSB, RO ; 
10S: 

RET 

. END START 


Flush any I/O on queue 
Reset terminal characteristics 


QIO error -— branch. 
Get the terminal driver status. 
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Example 8-2 is an example of the read verify function. The program 
shows a typical build of itemlists (both the right and left fields), channel 
assignment, a right- and left-justified read verify operation, and then the 
read QIO operation. 


Example 8-2 Read Verify Program Example 





.TITLE READ VERIFY - Read Verify Coding Example 
-IDENT ‘’V05-000’ 


-SBTTL DECLARATIONS 
. DISABLE GLOBAL 


; Declare the external system routines and MACRO libraries. 


. EXTERNAL LIBSGET_EF 

. EXTERNAL SCRSERASE_ PAGE 

. LIBRARY ‘ SYSSLIBRARY:LIB.MLB’ 

. LIBRARY ’ SYSSLIBRARY: STARLET .MLB’ 


; Include files: 


SIODEF 
STRMDEF 


Macros: 


Ne 


.-MACRO ITEM LEN=0, CODE, VALUE 
.WORD LEN 
.WORD  TRMS$ 'CODE’ 
.LONG VALUE 
.LONG 0 

.ENDM ITEM 


; Equated symbols: 
INBUF_LEN = 20 
ESC = *X1B 


Own storage: 


se Se Me Ne 


Build item lists for the read verify QIO 


; Right-justified field 


R_ITEM_LIST: 


ITEM CODE = MODIFIERS, - 
VALUE = TRMSM TM R JUST ; Right justify 
ITEM CODE = EDITMODE, - 
VALUE = TRMS$K_EM RDVERIFY ; Enable read verify 





(continued on next page) 


8-70 


Example 8-2 (Cont.) Read Verify Program Example 


Terminal Driver 


8.6 Terminal Driver Programming Examples 





ITEM 


ITEM 


ITEM 


ITEM 


ITEM 


R_ITEM LIST LEN 


R_PROMPT_ADDR: 
.ASCII 
R_PROMPT LEN = 


R_INISTR_ADDR: 
.ASCII 
R_INISTR_LEN = 


CODE = PROMPT, - 

VALUE = R_PROMPT ADDR, - 
LEN = R_PROMPT_LEN 
CODE = INISTRNG, - 
VALUE = R_INISTR_ADDR, - 
LEN = R_INISTR_ LEN 
CODE = INIOFFSET, - 
VALUE = R_INISTR_LEN 
CODE = PICSTRNG, - 
VALUE = R_PICSTR_ADDR, - 
LEN = R_PICSTR_ LEN 
CODE = FILLCHR, - 

VALUE = <*A/* /> 


.-R_ITEM LIST 


<ESC>/[12;12HS/ 


.-R_PROMPT ADDR 


/ y 


.-~R_INISTR_ADDR 


MASK = TRMS$M_CV_NUMERIC! TRMSM_CV_NUMPUNC 


R_PICSTR_ADDR: 
-BYTE 
. BYTE 
. BYTE 
. BYTE 
.BYTE 
. BYTE 
.BYTE 

R_PICSTR_LEN = 


7 


MASK 
MASK 
MASK 
i) ; 
MASK 
MASK 
MASK 


.-R_PICSTR_ADDR 


; Left-justified field 


L_ITEM_ LIST: 
ITEM 


ITEM 


ITEM 


ITEM 


7; Set 


, Set 


7; Set 


clear 


Marker character 


up prompt 


up initial string 


up picture string 


= *, fill = space 


CODE = MODIFIERS, - 
VALUE = TRMSM TM CVTLOW!TRMSM TM AUTO TAB 
; Upcase input and 
; complete on field full 
CODE = EDITMODE, - 
VALUE = TRM$K_EM RDVERIFY ; Enable read verify 
CODE = PROMPT, - 
VALUE = L_PROMPT_ADDR, - 
LEN = L_ PROMPT LEN ; Set up prompt 
CODE = INISTRNG, - 
VALUE = Lb. INISTR ADDR; = 
LEN = L_INISTR_LEN ; Set up initial string 
CODE = INIOFFSET, - 
VALUE = 0 
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ITEM CODE = PICSTRNG, - 
VALUE = L_PICSTR_ADDR, - 
LEN = L_PICSTR_LEN 
ITEM CODE = FILLCHR, - 
VALUE = <‘A/* /> 


L_ITEM LIST LEN 


.-L_ITEM_LIST 


L_ PROMPT ADDR: 
. ASCII 
L_ PROMPT LEN 


<ESC>/[13;12H Enter Date: 
.~L_PROMPT ADDR 


/ 


L_INISTR_ADDR: 
.ASCII 
L_INISTR_LEN 


- / 
.-L_INISTR_ADDR 


; Set up picture string 


* 


; clear , fill = space 


MASK1 = TRMSM_CV_NUMERIC 
MASK2 = TRM$M_CV_UPPER!TRMS$M_CV_LOWER 
L. PICSTR, ADDR: 
- BYTE MASK1 
- BYTE MASK1 
. BYTE 0 ; Marker character 
- BYTE MASK2 
-BYTE MASK2 
BYTE MASK2 
- BYTE 0 ; marker character 
-BYTE MASK1 
-BYTE MASK1 
L_ PICSTR_LEN = .7L_PICSTR_ADDR 
IN_IOSB: -BLKL 2 
TT CHAN: .» BLKW 1 
INBUF: . BLKB INBUF_LEN 
SYSINPUT: -ASCID /SYSSINPUT/ 
SYNC_EFN: . BLKL 1 
» PAGE 
-ENTRY READ VERIFY “M < > 


“Ne 


; Get the required event flags. 


‘we 


PUSHAL SYNC_EFN 
CALLS # 1, G* LIBSGET_EF 
BLBC RO, ERROR 


; Assign the channel to SYSSINPUT 


Ne 


SASSIGN_S - 
CHAN = TT_CHAN - 
DEVNAM = SYSINPUT 
BLBC RO, ERROR 


; Clear the screen 


‘Ne 
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; Error - branch 


; SYSSINPUT 
; Branch on error 
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CLRQ - (SP) 
CALLS #2, G* SCRSERASE PAGE 
BLBC RO, ERROR 


; Do the right-justified read operation 


PUSHL #R_ITEM LIST LEN 
PUSHAB R_ITEM LIST 
CALLS #2, DO READ 

BLBC RO, ERROR 


+ Do the left-justified read operation 


PUSHL #L ITEM LIST LEN 
PUSHAB L_ITEM LIST 
CALLS #2, DO READ 


BLBC RO, ERROR 
ERROR: 

RET 

- PAGE 
,re 


. 
f 


; DO_READ - do the actual QIO 
; Inputs: 


c 4 (AP) the address of the itemlist 
; 8 (AP) the length of the itemlist 


-ENTRY DO READ, “M<> 


SQIOW_S EFN=SYNC_EFN, - 
CHAN = TT CHAN, - 
FUNC = #<IO$ READVBLK!IO$M EXTEND>, —- 
IOSB = IN_IOSB, - 


pl = inbuf, - 
p2 = #inbuf_len, - 
ps = 4(AP), a 
P6 = 8 (AP) 
BLBC RO, 10$ ; QIO error - branch 


MOVZWL IN_IOSB, RO Get the terminal driver status. 
BLBC RO, 10$ ; Terminal driver error ~ branch 


‘Ne 


; Handle the input... 


108: 
RET 


-END READ VERIFY 
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LAT Application Device Program Example 


Example 8-3 requests a connection to an applications (LT) device. The 
program uses the terminal port function code (IO$_TTY_PORT) and the 
function code modifiers for the LAT port driver to solicit the connection 
to the applications device. (Note that the IO$_TTY_PORT function is not 
specific to LAT operations.) 


Example 8-3 also illustrates the use of the set rating (IO$M_LT_RATING) 
and map port (IO$M_LT_MAP_PORT) functions (see Section 8.4.4.1). 


See Section 8.4.4.2 for additional information on LAT application 


programming. 


Example 8-3 LAT Application Device Program 





. TITLE 
- IDENT 


LAT APPLICATION DEVICE PROGRAMMING EXAMPLE 


reach, 


eKKEKEKKKKKKKKK KEKE KKK KKEKKKEKKK KKK KERR KE KKKKKKKKEKKRKKKKKKRKKKKRKKKKEKKE 


, 
° 
, 
, 
tA 
, 


.-SBTTL 
- DISABLE 


LAT Application Device Program 


DECLARATIONS 
GLOBAL 


eC KK KK KKK KK KEK KK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KEK KKKKKKKKEK 


; Declare the external system routines and libraries. 


- EXTERNAL 
. LIBRARY 
. LIBRARY 


; Define symbols 


SIODEF 
SQIODEF 
SSSDEF 


. 
, 


; Declare the required event flags 


° 
a, 


SYNC_EFN:: 
ASYNC_EFN: : 


Declare exit handler control block 


- BLKL 
-BLKL 


; 
; 
EXIT_HANDLER_BLOCK: 


- LONG 
- LONG 
. LONG 
. LONG 
STATUS: 


0 


EXIT HANDLER 


1 
STATUS 
-BLKL 


LIBSGET_EF 


’‘ SYSSLIBRARY: LIB.MLB’ 
' SYSSLIBRARY: STARLET .MLB’ 


al 
cl 


nl 


7 


T/O function codes 


; QIO definition codes 


System Service completion codes 


System uses this for pointer 
Address of exit handler 
Argument count for handler 
Destination of status code 
Status code from SEXIT 





8-74 


(continued on next page) 


Terminal Driver 
8.6 Terminal Driver Programming Examples 


Example 8-3 (Cont.) LAT Application Device Program 





; Allocate terminal descriptor and channel number storage 


. 
7 


TT DESC: -ASCID /SYSSINPUT/ ; Name of terminal 
TT CHAN: . BLKW 1 ; TT channel number storage 
LT DESC: -ASCID /LATSPORT/ ; Logical name of LT device, 


; define this to be the application 
# port created in LATCP 
LT CHAN: - BLKW J ; LT channel number storage 


° 
, 


; Define carriage control symbols 


CR=*X0D ; Carriage return 
LF=*X0A ; Line feed 


; Define I/O buffer sizes 
IN_BUFLEN = 80 ; Input buffer size 
OUT_MSGLEN = 2 ; Initial length of output message 


; Allocate I/O buffers; OUT_MSG must appear before IN_BUF. The effect of this 
; is to prefix <CR><LF> to the bytes read from the TT device. By adding two 

7 to the number of bytes read, and using the buffer starting at OUT_MSG, the 

; message written to the LTA device will be the message read from the TT device 
; prefixed with <CR><LF>. 


OUT_MSG: -ASCII <CR><LF> ; Start address of output buffer 
IN_BUF: - BLKB IN_BUFLEN ; Allocate character input buffer 


; Allocate I/O status blocks (IOSBs) 


° 
f 


IN_IOSB: -BLKQ 1 ; Input I/O status block (IOSB) 
OUT _IOSB: -BLKQ 1 ; Output I/O status block (IOSB) 
SOL_IOSB: -BLKQ 1 ; Solicitation connect IOSB 
MAP IOSB: -BLKQ x + Map IOSB 
RATING IOSB: - BLKO L ; Rating IOSB 
SYNC_IOSB: . BLKQ 8 ; IOSB for synchronous operations. 
ASYNC_IOSB: - BLKO Zz ; IOSB for asynchronous operations. 
SERVICE DESC: . LONG SERVICE NAME LENGTH 

-ADDRESS SERVICE NAME 
SERVICE_NAME: -ASCII /TIMESHARING/ ; Service that was created by LATCP 
SERVICE NAME LENGTH = . - SERVICE NAME 
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NEW_RATING: - LONG 100 ; The new static rating value for it 


LATNOD: .ASCII /PLUTO/ 


NODLEN= .-LATNOD 
LATPORT: .ASCII /APPLIC_DEVICE/ 


PORTLEN= .-LATPORT 
LINKNAM: .ASCII /LATSLINK/ 


LINKLEN= .-LINKNAM 


MAP_ITEMLIST: 
.WORD NODLEN 
.WORD IO$V_LT_MAP_NODNAM 
.ADDRESS LATNOD 
.LONG 0 


.WORD  PORTLEN 

.WORD IO$V_LT_ MAP PORNAM 
.ADDRESS LATPORT 

.LONG 0 


.WORD LINKLEN 

.WORD IO$V_LT MAP LNKNAM 
-ADDRESS LINKNAM 

.LONG 0 


. LONG 0 


; Define output messages 


; Messages are accessed by indexing into a table of longwords 
7; With each message described by a message address and length. 
; Although not done here, this table should be large enough 

; to accomodate all possible reject reasons. 


MSG TABLE: ; Table of message address 
; and length 
. LONG 01$ ; First message address 
. LONG 05$ ; First message length 
. LONG 10$ ; Message address 
. LONG 15$ ; Message length 
. LONG 20$ + Message address 
. LONG 25$ + Message length 
. LONG 30$ ; Message address 
. LONG 35$ ; Message length 
. LONG 40$ ; Message address 
. LONG 45$ 7 Message length 
. LONG 50$ ; Message address 
. LONG 558 7 Message length 
. LONG 608 ; Message address 
. LONG 65$ ; Message length 
. LONG 190$ ; Message address 
. LONG 1955 ; Message length 
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. 
, 


; Messages (Refer to the list of LAT rejection codes in Table 8-16.) 


01S: -ASCITI 


05$=.-01$ 
108: -ASCII 
15$=.-10$ 
208: . ASCII 
25$=.-205S 
30S: -ASCII 
35$=.-305$ 
408: -ASCITI 
455=.-405$ 
508: -ASCIT 
55$=.-50$ 
608: ASCII 
65$=.-60$ 
1908S: -ASCII 


195$=.-1905 


NOTCON: .ASCII 


NOTCONL=.-NOTCON 


° 
, 


/REASON UNKNOWN/ 


<CR><LF>/CONNECTION ESTABLISHED/ 


/SYSTEM SHUTDOWN IN PROGRESS/ 


/REASON UNKNOWN/ 


/REASON UNKNOWN/ 


/INSUFFICIENT RESOURCES/ 


/PORT OR SERVICE IN USE/ 


/ILLEGAL REQUEST PARAMETERS/ 


<CR><LF>/CONNECTION REJECTED — / 


; Static QIO packets for message output using QIOS G form 


WRITE QIO: 
$QIO 


ERROR_QIO: 
$QIO 


FUNC=IO0O$_ WRITEVBLK!IO$M BREAKTHRU! IOSM_REFRESH, — 
EFN=1 


FUNC=I0$_WRITEVBLK! IO$M_BREAKTHRU! IOSM_REFRESH, — 
EFN=1 
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. PAGE 
-SBTTL MAIN ROUTINE 
ptt 


+ Functional description: 


FRAKKRKKKKKK KE KK KK KKK KKK KKK KK KK KKK KK KK KKK KKK KKK KKK KEKE KKKEK KKK 


; Main Program Routine 


PRKKRKRRKKKKK KKK KKK KKK KKK KKK RK KKK KKK KK KKK KR KK KEK KKK KK KKK KKK K 


; The following code assigns a channel to the LTAxxx: 

; application device and attempts to create a connection to 
7 that device. The connection status is displayed on 

; the user’s terminal. Input from the user’s terminal 

; is output on the LTAxxx device: CTRL/C entered by the 

; user terminates the program. 


; Input parameters: 
; None 


7; Output parameters: 
; None 


-ENTRY START “M <> ; Entry mask 
; Get the required event flags. 
PUSHAL ASYNC_EFN 
CALLS #1, G*“LIBSGET_EF 
BLBC RO,20$ ; Error - branch 
PUSHAL SYNC_EFN 
CALLS #1, G*“LIBSGET_EF 
BLBC RO,20$ ; Error - branch 


; Assign channels 


SASSIGN_S DEVNAM=TT DESC, - 
CHAN=TT_CHAN 


Assign channel to user’s 
terminal 


se Se Ne 


BLBC RO, 20$ Error - branch 

SASSIGN_S DEVNAM=LT_DESC, —- ; Assign channel to LT device 
CHAN=LT_CHAN 

BLBC RO, 205 ; Error - branch 


Declare an exit handler which will execute at image exit. 


“oe Me Ne 


$SDCLEXH_S DESBLK=EXIT HANDLER BLOCK 
BLBC RO, 20S ; Error - branch 
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; Perform the privileged operations of changing a static service 
; rating (an operation unrelated to the use of application devices but 
; included here strictly as an example) and remapping the applications 
; port. 
BSBW LAT _SET_RATING ; Change a static service rating 
BLBC RO, 20S ; Error - branch 
BSBW LAT_MAP PORT ; Change the application port mapping 
BLBC RO, 20$ ; Error - branch 


; Enable CTRL/C on user terminal and CTRL/Y on LTA device. Solicit 
: connection to application device and post read to user’s terminal. 
7 The CTRL/Y AST enable is done in the solicit connection AST so 

: that a CTRL/Y is not returned before the solicit AST. This 


; prevents the rejection errors from being displayed. 

BSBW ENABLE CTRLCAST ; Enable CTRL/C ASTs 

BLBC RO, 20S ; Error - branch 

BSBW SOL_CONNECT ; Try to connect to LT device 

BLBC RO, 20$ ; Error - branch 
LOS: 

SHIBER_S ; Wait for a while. 

BLBS RO, 10$ ; Keep looping until CTRL/C 
205': 

BRW ERROR 

- PAGE 

. SBTTL ENABLE CTRLYAST —- Enable CTRLYAST on LTAxxx device 
ptt 


; Functional description: 


° 
, 


: Routine to allow hangup notification. This routine enables 
; CTRL/Y AST delivery for the LTAxxx: device. The CTRL/Y AST 
; is called if an abnormal termination occurs to the remote 

: application device. 


. 
a, 


; Input parameters: 
7 None 
; Output parameters: 


; RO = QIO status. 


° 
’ 


ENABLE CTRLYAST: 

$QIO_S CHAN=LT_CHAN, - 
FUNC=#10$ SETMODE! IOSM_CTRLYAST, - 
IOSB=ASYNC_IOSB,- 
ASTADR=START_READ, - Start Read at completion of QIO 
P1=HANGUP, - ; AST routine address 
P3=#3 ; User mode 

BLBC RO, 10$ QIO error - branch 

RSB 


~e 


me 
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10S: 

BRW ERROR 

.PAGE 

.SBTTL HANGUP - AST Routine for CTRL/Y 
phe 


. 
’ 


; Functional description: 

; AST routine to execute when CTRL/Y status is returned for the 
: application device. This status is returned when the 

; connection to the remote device is abnormally terminated. 

; Input parameters: 


; None 


; Output parameters: 


? None 
HANGUP : 
. WORD “M<> 
MOVZWL #SSS_HANGUP, RO ; Indicate hangup 
BRW ERROR ; and exit 
. PAGE 
-SBTTL START_READ - Start reads on the TT device 


p++ 
; Functional description: 


; This routine executes at completion of the SETMODE QIO to set the CTRL/Y 
7 AST. It checks the completion status of the QIO, and starts reads on the 
F TT device by calling ENABLE READ. 

; Input parameters: 

; None 

; Output parameters: 

; None 


, 
START READ: 
- WORD “M<> 


BLBC ASYNC_IOSB,10$ ; Terminal driver error - branch 
BSBW ENABLE READ 
RET 
10S: 
MOVZWL ASYNC_IOSB, RO ; Put error status in RO 
BRW ERROR 
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ptt 


° 
, 


. PAGE 
-SBITL 


ENABLE READ - QUEUE A READ TO THE TERMINAL 


; Functional description: 


Routine to queue a read to the terminal. The queued 
read will not affect writes due to the fact that 
breakthru has been set for writes. 


; Input parameters: 


None 


; Output parameters: 


RO = Successful QIO status. 


ENABLE READ: 


10S: 


ptt 


e 
? 


~ $Qro_s 


BLBC 
RSB 


BRW 


- PAGE 
-SBTTL 


EFN=ASYNC_EFN, — ; Must not be QIOW form 
CHAN=TT CHAN, - 

FUNC=#I0$ READVBLK, - 

IOSB=IN_IOSB, - 

ASTADR=READAST, - 

P1=IN_ BUF, - 

P2=#IN_BUFLEN 

RO, 10S ; QIO error - branch 


ERROR 


READAST - AST Routine for Read Completion 


; Functional description: 


AST routine to execute on read completion. The data that 
was input from the users terminal is output on the 


application device. Another read request is then posted. 


; Input parameters: 


None 


; Output parameters: 


None 
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-ENTRY READAST *M < R2, R3, R4, R5 > ; Procedure entry mask 

BLBC IN_IOSB, 10$ ; Terminal driver error - branch 

MOVZWL IN_IOSB+2, RO ; Get number of characters read 

ADDL2 #OUT_MSGLEN, RO ; Add size of fixed ack 

$QIO_S EFN=ASYNC_EFN, - ; Output message to LT device 
CHAN=LT CHAN, - 7 Must be asynchronous (QIO) 


FUNC=#10$ WRITEVBLK, - 
IOSB=OUT IOSB, - 
ASTADR=WRITEAST, - 
P1=OUT_MSG, - 


P2=R0 

BLBC RO, 20$ ; QIO error - branch 

BSBW ENABLE READ ; Queue next read 

RET 
10S: 

MOVZWL IN_IOSB, RO ; Put error status in RO 
20S: 

BRW ERROR ; Exit with error 

. PAGE 

-SBTTL WRITEAST - AST Routine for Write Completion 
ptt 


; Functional description: 


7 AST routine to execute on write completion. Check the status 
; of the write. 


; Input parameters: 
; None 


7; Output parameters: 


; None 

pe 
-ENTRY WRITEAST *M < R2, R3, R4, R5 > ; Procedure entry mask 
BLBC OUT_IOSB, 10$ ; Terminal driver error - branch 
RET 

10S: 
MOVZWL OUT_IOSB, RO ; Put error status in RO 
BRW ERROR 
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- PAGE 

.SBTTL ENABLE CTRLCAST - ENABLE CTRL/C AST 
att 
; Functional description: 


; Routine to allow CTRL/C recognition on user’s terminal 
> Input parameters: 

; None 

; Output parameters: 


; RO = QLO/Terminal driver status. 


, 


ENABLE CTRLCAST: 
SQIOW_S EFN=SYNC_EFN, - 
CHAN=TT_ CHAN, - 
FUNC=#10$ SETMODE!IOSM _CTRLCAST, - 
IOSB=SYNC_IOSB, - 


PL=CTRLCAST, - ; AST routine address 
P3=#3 ; User mode 
BLBC RO, 10$ ; QIO error - branch 
MOVZWL SYNC_IOSB, RO ; Get the terminal driver status. 
10S: 
RSB 
-PAGE 
-SBTTL CTRLCAST - AST Routine for CTRL/C 
ptt : 


. 
tA 


; Functional description: 


; AST routine to execute when CTRL/C is received. The connection 
; to the application device is stopped and the program is terminated 
; with normal completion status. 


; Input parameters: 
? None 
; Output parameters: 


; None 


CTRLCAST: 

- WORD “M<> 

$QIO_S EFN=ASYNC_EFN, - ; Disconnect session to LT device 
CHAN=LT CHAN, - 
FUNC=#1I0$ TTY PORT!IOSM LT DISCON, - 
IOSB = ASYNC_IOSB,- 
ASTADR = DISCONNECTAST 

BLBC RO, 10S 7; QIO error - branch 

RET 
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10S: 

BRW ERROR 

- PAGE 

.SBTTL DISCONNECTAST - AST Routine for disconnect status 
ptt 


° 
’ 


; Functional description 

; AST routine to execute when disconnect is complete. The image 
; will exit with the status from the disconnect QIO by moving the 
; value in the status field of the IOSB into RO. 

; Input parameters: 


: None 


; Output parameters: 


ie None 
DISCONNECTAST: 

- WORD “M<> 

MOVZWL ASYNC_IOSB, RO ; Save disconnect status 
ERROR: 

SEXIT_S CODE=RO ; Exit 

RET 

- PAGE 

.SBITL SOL_CONNECT - Solicit Connection to LT Device 
ptt 


° 
, 


; Functional description: 


i This routine issues the QIO to the LT driver to solicit 
. the connection to the LT device. 


7 Input parameters: 
: None 
; Output parameters: 


RO = QIO status. 


OL_CONNECT: 
$QI0_S EFN=SYNC_EFN, - 
CHAN=LT CHAN, - 
FUNC=#10$ TTY PORT!IO$M_LT CONNECT, - 
IOSB=SOL_IOSB, - 
ASTADR=SOLAST 
RSB 


» PAGE 
.SBTTL SOLAST - AST Routine for connection solicitation status 
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ptt 
; 


; Functional description: 

; AST routine to execute when connection 
: complete. If status is success, print 
: return. If status is rejection, print 
; reject reason, and exit. If status is 
; Input parameters: 


. None 


; Output parameters: 


; None 

SOLAST: 
. WORD “M<> 
MOVZWL SOL_IOSB, RO ; 
BLBC RO,10$ : 
MOVL RO,R1 ; 
JSB WRITE STATUS ; 
BSBW ENABLE CTRLYAST ; 
RET 

10S; CMPW RO, #SS$_ABORT ; 
BNEQO ERROR 7 
MOVZWL TT CHAN, ERROR_QIO+8 ; 
SQIOW_G ERROR_QIO ? 
MOVZWL SOL_IOSBt+2,R1 : 
BSBB WRITE STATUS ? 
BRW ERROR ; 

WRITE STATUS: 
MOVQ MSG TABLE[R1],- ; 

WRITE QIO+QIO$ Pl 

MOVZWL TT CHAN,WRITE_QIO+8 ; 
SQIOW_G WRITE QIO 
RSB 


solicitation is 
success message and 
reject message, 
otherwise, exit. 


Get return status 

If clear, error 

Copy success code for index 
Output success message 
Enable CTRL/Y ASTs 


Is this a rejected connection? 
If eq, output error message 
Insert channel into QIO packet 
Output error message first 

Set Rl for offset into table 
Output error reason 

Exit 


Put message into QIO 


Insert channel into QIO packet 
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- PAGE 
-SBTTL EXIT HANDLER: 
Per 


; Functional description: 


; Exit handler routine to execute when image exits. It will 
; cancel any outstanding I/O on these channels. 


; Input parameters: 
; None 
; Output parameters: 


; None 


EXIT _HANDLER: 
. WORD 
SCANCEL_S CHAN=TT_CHAN 
SCANCEL S CHAN=LT_CHAN 
RET 


- PAGE 


7; Flush any output 


- SBTTL LAT MAP PORT Map Port QIO 


ptt 
; 


+ Functional description: 


; The following code performs a map port QIO. It uses an item 
; list that specifies the names for the target server and port 
; that is associated with the application port. 


; Input parameters: 
; None 
; Output parameters: 


; RO = QIO/Terminal driver status. 


LAT_MAP PORT: 
SQIOW_S EFN = SYNC_EFN, - 


CHAN = LT_CHAN, —- 
FUNC = 

IOSB = MAP _IOSB, - 
Pl = MAP ITEMLIST 


BLBC RO, 10$ 
MOVZWL MAP IOSB, RQ 


#<IO$_ TTY PORT! IOSM_LT MAP PORT>, - 
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108: 
RSB 
. PAGE 
. SBITL 
ett 


° 
, 


LAT SET RATING 


7 Functional description: 


7 The following code performs the set rating QIO. 
; In this example, the rating for the service "TIMESHARING" 
; is set to a static rating of 100. 


7; Input parameters: 


; None 


; Output parameters: 
; RO = QI0/Terminal driver status. 


’ 


LAT SET RATING: 


SQIOW_S EFN = SYNC_EFN, - 


CHAN = LT CHAN, - 


FUNC = #<IO$ TTY PORT!IO$M LT RATING>, - 
IOSB = RATING _IOSB,- 
Pil = SERVICE DESC, - 
P2 = NEW_RATING 
BLBC RO, 10$ ; Error - branch 
MOVZWL RATING IOSB, RO 
10S: 
RSB 
.END START 
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This chapter describes the use of the VMS pseudoterminal driver 
(FTDRIVER) and the VMS pseudoterminal software. 


A pseudoterminal is a software device that appears as a real terminal 

to an application communicating with it but that does not require the 
existence of a physical terminal. A pseudoterminal consists of two 
components: the pseudoterminal device and a control program. The 
control program acts like a keyboard; that is, anything written to the 
control program appears on the pseudoterminal device as if the keystrokes 
had been typed in at a physical terminal. The control program also acts 
like a viewport to the pseudoterminal device; that is, the control program 
reads anything that is written by the system to the pseudoterminal device. 


A pseudoterminal allows an application to be set up on the control 

side of the link to communicate with another application that is on the 
pseudoterminal side. This arrangement allows development of applications 
that either simulate users or monitor the communication between a real 
user (at a physical terminal) and an application. As with other devices, 
the work of the pseudoterminal is performed by a device driver and is 
tightly coupled to the operating system. 


The VMS pseudoterminal driver software includes a set of control 
connection routines. Applications can use these routines to perform 
pseudoterminal operations and functions. Appendix C provides the VAX 
calling standards for these routines. 





9.1 Pseudoterminal Operations 


This section contains information on the following pseudoterminal 
operations: 


¢ Creating a pseudoterminal 
¢ Canceling a request 


¢ Deleting a pseudoterminal 


9.1.1 Creating a Pseudoterminal 


To create a pseudoterminal, use the PTD$CREATE routine described in 
Appendix C. When a pseudoterminal is created, it inherits the current 
system terminal default attributes unless you specify an alternate set of 
characteristics. In either case, you cannot use PTD$CREATE to alter the 
following startup attributes: 


¢ TT$M_CRFILL is cleared. To change this attribute, issue the SET 
MODE $QIO function. 


¢ TT$M_LFFILL is cleared. To change this attribute, issue the SET 
MODE $QIO function. 
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¢ TT$M_MODEM is cleared. This attribute cannot be changed. 
¢ TT$M_REMOTE is cleared. This attribute cannot be changed. 


¢ TT$M_HOSTSYNC is set. To change this attribute, issue the SET 
MODE $QIO function. 


¢ TT$M_TTSYNC is set. To change this attribute, issue the SET MODE 
$QIO function. 


¢ TT2$M_DMaA is cleared. To change this attribute, issue the SET 
MODE $QIO function. Changing it does not alter the behavior of 
TTDRIVER or the pseudoterminal. 


¢ TT2$M_AUTOBAUD is cleared. To change this attribute, issue the 
SET MODE $QIO function. Changing it does not alter the behavior of 
TTDRIVER or the pseudoterminal. 


¢ TT2$M_FALLBACK is cleared. To change this attribute, issue the SET 
MODE $QIO function. 


¢ TT2$M_HANGUP is cleared. To change this attribute, issue the SET 
MODE $QIO function. 


¢ TT2$M_DCL_MAILBxX is cleared. This attribute cannot be changed. 


When you create a pseudoterminal, you can specify a repeating 
asynchronous system trap (AST) to be delivered when the terminal 
connection is freed. This AST can be supplied only when the 
pseudoterminal is created, and it cannot be deleted. A terminal is freed 
when a process logs out or deassigns the last channel to the device. The 
AST allows the control program to determine whether or not a user of a 
pseudoterminal is using it. At this point, the control program can reuse or 
delete the pseudoterminal by deassigning the control channel. 


9.1.2 Canceling a Request 


To cancel a queued control connection request, the control program uses 
the PTD$CANCEL routine. This routine enables the pseudoterminal 
driver to differentiate between control requests and terminal requests that 
are being canceled. This routine cannot be used to flush event notification 
ASTs. 


9.1.3 Deleting a Pseudoterminal 
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To delete the pseudoterminal, the control program uses the PTD$DELETE 
routine. When a pseudoterminal is deleted, any process that is using the 
pseudoterminal (except the control process) is disconnected. If you have 
the TT2$M_DISCONNECT bit set in the default terminal characteristics 
parameter (TTY_DEFCHAR2) and virtual terminals have been enabled 
(see Section 8.2.2.3), you get a virtual terminal upon logging in to a 
pseudoterminal. In this case, the process is not logged out, but the virtual 
terminal is disconnected from the pseudoterminal. 
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The PTD$DELETE request causes any pending I/O for the control program 
to be aborted. It deletes any queued event notification ASTs and returns 
the I/O buffers to the application. It also causes the pseudoterminal unit 
control block (UCB) to be deleted once the reference count returns to zero. 


Note: If an application exits without calling PTD$DELETE, the 
pseudoterminal is still deleted. 





9.2 Pseudoterminal Driver Features 


The terminal portion of a pseudoterminal is similar to a regular VMS 
terminal. The pseudoterminal driver provides the following features: 


e Type-ahead 

e Specifiable or default line terminators 

¢ Special operating modes, such as NOECHO and PASTHRU 
e Escape sequence detection 

¢ Terminal/mailbox interaction 


¢ Terminal control characters, such as Ctrl/S and Ctrl/Q for starting and 
stopping output, Ctrl/O for discarding output, and all other special 
characters that are handled by the standard VMS terminal driver 


¢ Limited full-duplex operation (simultaneously active read and write 
requests) 


For more information on these features, see Section 8.2. 


9.3 Pseudoterminal Driver Device Information 


The pseudoterminal inherits its device characteristics from the system 
default parameters, with the following exceptions: 


¢ The device inherits initial device characteristics from the SYSGEN- 
supplied default values. You can modify the device characteristics 
during device creation by supplying new characteristics. 


¢ The HOSTSYNC terminal characteristic is always set. 
¢ The device is set to NOMODEM and cannot be set to MODEM. 


e The device is set not to time output character transmission. Hardware 
controllers time output character transmission to determine whether 
the controller is broken. 


You can obtain information on pseudoterminal characteristics by using the 
Get Device/Volume Information ($GETDVI) system service, as described 
in Section 8.3, and the VMS System Services Reference Manual. For 
pseudoterminals other than the template unit FTAO, you can also use 

the sense mode functions described in Section 8.4.5 to read terminal 
characteristics, and the set mode function described in Section 8.4.3 to 
change terminal characteristics. 
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9.4 1/O Buffers 


When you create a pseudoterminal, you must provide at least one page to 
be used as an I/O buffer. You should allocate no more than six I/O buffers 
for each pseudoterminal. Each page becomes one I/O buffer, and no read 
or write request can reference more than one I/O buffer at a time. The 
I/O buffers must be page aligned; therefore, you should create these pages 
with the $EXPREG system service or the LIB${GET_VM_PAGE routine. 
These pages are owned by the driver until you delete the pseudoterminal. 
The application is responsible for managing these pages. The application 
cannot use buffers that are owned by another pseudoterminal; it must 
decide whether to delete the buffers when they are freed by the driver or 
to reuse them. 


The I/O buffers must be valid pages in virtual address space. Creating 
or deleting an I/O buffer does not alter the contents of the pages. An 
application is free to use these buffers in any way that it chooses. A 
request must fit within one I/O buffer. Attempts to span an I/O buffer 
result in an error. Additionally, a longword of status information must fit 
into the I/O buffer; this limits the largest request to 508 bytes. The low- 
order word of the status information longword contains the status of the 
request. The high-order word of the status information longword contains 
the actual number of bytes that are read or written. 


Assume that an I/O buffer starting at 200 hexadecimal is available for 
use. If you want to read 20 bytes from the pseudoterminal, the readbuf 
address would be 200, and the readbuf_len would be 20. An application 
can use the rest of this buffer for other purposes, including reading or 
writing to the pseudoterminal. Figure 9—1 shows how the buffer would 
look. 


Figure 9-1 Buffer Layout 





Byte Count 


Pm 


Po 


ZK~9656-GE 


20046 
204.46 





21846 





9.5 Pseudoterminal Functions 


This section discusses the following pseudoterminal functions: 


e Reading data 
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9.5.1 


9.5.2 


9.5.3 


Reading Data 


Writing Data 
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¢ Writing data 
¢ Using write with echo 
¢ Flow control 


e Event notification 


To read data from the pseudoterminal, the control program uses the 
PTD$READ routine. The read request completes with a minimum of 1 
character and a maximum of the number of characters requested. The 
read operation completes when the pseudoterminal has characters to 
output. If a read request is issued and no data is available, the read 
request is queued and then completed at a later time. 


An application that issues an asynchronous pseudoterminal read can use 
the $SYNCH system service to find out when the read completed. The efn 
argument for the $SYNCH service must be the same as the efn specified 
in the original PTD$READ call, and the iosh for the $SYNCH service 
must match the readbuf of the PTD$READ call. 


To write data to the pseudoterminal, the control program uses the 
PTD$WRITE routine. The largest write possible is 508 bytes. The write 
request allows you to specify a buffer to receive any output generated 
by the write; you do not need to issue a separate read request to read 
this data. Using an echo buffer allows a control application to reduce 
significantly the number of I/O requests required. 


An application can issue only one write request at a time. Once the write 
request completes, the application must check the write buffer status 
longword to see whether all the data supplied was written. If not, the 
application must issue additional write requests until all the data has 
been accepted. 


Using Write with Echo 


If a read request is pending when a write-with-echo request is issued, the 
echo data is placed in the echo buffer. If more data is echoed than can 

fit in the echo buffer, the remaining data is placed in the pending read 
requests buffer. If no pending read exists, the data is held by the driver 
until another request that can take the data is issued. Both the read and 
the write with echo must use completion ASTs to allow the driver to report 
request completions to the application in the correct order. 


If an application is not using the write-with-echo capability, the application 
should avoid using completion ASTs if possible. Unnecessary use of 
completion ASTs significantly increases the number of instructions needed 
to complete a read or write operation. 
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9.5.4 Flow Control 


When using write with echo, both the wrtbuf and echobuf arguments 
contain I/O status information. An application must check both of these 
status longwords if the PTD$WRITE completes successfully. If a write 
operation wrote no characters, characters might still be in the echo buffer. 
If no data was echoed, the status in the echobuf is SS$ NORMAL with 
zero bytes transferred. 


By default, the driver attempts to notify the control program of data 
overrun or loss. The pseudoterminal sends an XOFF AST when the type- 
ahead buffer is getting full. Once the pseudoterminal delivers an XOFF 
AST, the pseudoterminal also returns a status of SS$_DATAOVERUN 
with the actual number of characters input. This prevents a single request 
from flooding the type-ahead buffer. If a control program makes repeated 
attempts to insert data after receiving the SS$¢_DATAOVERUN message, 
it can flood the terminal type-ahead buffer. When the type-ahead buffer 
has filled, the pseudoterminal returns the status of SS$_DATALOST. 


If the control program is writing to the terminal or terminal driver, it 
should let the terminal and terminal driver handle flow control. To do 
this, the application should enable all three input flow control notification 
ASTs. The control program should write a DC1 to the terminal if an XON 
AST is delivered. It should write a DC3 to a terminal if an XOFF AST 

is delivered, and write a bell character to the terminal if the bell AST is 
delivered. These signals allow the terminal to decide what to do with the 
flow control data. The application should ignore the SS$_DATAOVERUN 
and SS$_DATALOST return status and continue writing data to the 
pseudoterminal. 


9.5.5 Event Notification 


9.5.5.1 
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This section describes how the pseudoterminal driver provides notification 
of important driver events. 


Input Flow Control 


The driver provides three ways to indicate when the class driver wants to 
stop input and one way to signal when it is safe to resume output. 


1 The driver returns a status of SS$_DATAOVERUN and the number of 
characters input for the control program write. 


2 The control program can enable a BELL attention AST to be 
delivered when the class driver calls the PTD$SET_TERMINAL_ 
NOTIFICATION routine. This AST is delivered if the pseudoterminal 
does not have the HOSTSYNC attribute set. If only a BELL or only an 
XOFF AST event is enabled and an XOFF or a BELL AST needs to be 
delivered, the AST that is available is delivered. 


3 The control program can enable an XOFF attention AST to be 
delivered when the class driver calls the PTD$SET_TERMINAL_ 
NOTIFICATION routine. This AST is delivered if the pseudoterminal 
has the HOSTSYNC attribute set. 


9.5.5.2 


9.5.5.3 


9.5.5.4 


9.5.5.5 


9.5.5.6 
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4 The control program can enable an XON attention AST to be 
delivered when the class driver calls the PTD$SET_TERMINAL_ 
NOTIFICATION routine. This AST is delivered only if the 
pseudoterminal has the HOSTSYNC attribute set. 


Output Stop 
The Output Stop AST tells the control program that the terminal driver is 
stopping output. This keeps the control program from having to determine 
whether an XOFF written to the control side is being treated by the 
terminal driver as flow control or data. 


Output Resume 
The Output Resume AST tells the control program that the terminal driver 
wants to resume output. This AST can be delivered at any time, even if 
output is active or has previously been stopped. The control program 
should always restart output processing when it receives this AST. 


Characteristics Changed 
The Characteristics Changed AST tells the control program that 
the terminal driver has called the pseudoterminal CHANGE 
CHARACTERISTICS routine. This routine is called whenever the 
terminal driver has changed the device characteristics. The control 
program should then read the pseudoterminal characteristics to determine 
what has changed. 


Output Abort 
The Output Abort AST tells the control program that the terminal driver 
has called the pseudoterminal ABORT OUTPUT routine. This routine is 
called when the terminal driver wants to flush any outstanding output 
data. The control program should flush any internally buffered data when 
this AST is received. 


Terminal Driver Read Events 
Three special event types notify the control program when a terminal 
read request starts and finishes. By default, the pseudoterminal does 
not deliver the read notification ASTs associated with these events. The 
PTD$SET_EVENT_NOTIFICATION routine must be used explicitly to 
enable or disable their delivery. 


¢ Start Read—tTells the control program that the terminal driver is 
starting a read request. Some applications require this in order to 
know when to start inputting a logged session script. 


¢ Middle Read—Tells the control program that the terminal driver has 
finished writing the prompt string if one was supplied. 


e End Read—Tells the control program that the terminal driver has 
finished a read request. 


Once an event notification AST is enabled, it continues to be delivered 
until it is canceled, or until the device is deleted. This characteristic allows 
the control program to enable the AST once, thus greatly reducing the risk 
of missing multiple rapid occurrences of an event. If the driver cannot 
get sufficient resources to deliver the notification AST, that report is lost. 
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Only one AST per event is allowed, and attempts to specify multiple ASTs 
result in use of the last one specified. 


To enable or disable event notification, the control program uses the 
PTD$SET_EVENT_NOTIFICATION routine, which is described in 
Appendix C. 


9.6 Pseudoterminal Driver Programming Example 


9.6.1 Design Overview 
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Example 9-1 illustrates how to use the pseudoterminal. This section 
begins with a brief overview of the example. The example itself briefly 
discusses each module; the pseudocode for that module follows its 
discussion. 


The scenario chosen for this example is a simple terminal session logging 
utility that uses most of the pseudoterminal capabilities. This example 
also illustrates how to use the write-with-echo capability, which provides a 
significant gain in performance. 


The design approach writes the log record in a main loop that hibernates 
when it has no work to do. The loop uses ASTs to read keystrokes from 
the terminal, write to the pseudoterminal, and write data to the terminal. 
When a block of characters is written to the terminal, that block is placed 
into a queue of blocks to be written to the log file, and a wake request is 
issued. Logging is stopped if you log out of the subprocess, if you enter 
the stop logging character Ctrl\, or if a severe error occurs during data 
processing. When any of these events occur, all outstanding log records 
are written before the program exits. 


One major design consideration is how flow control should be handled— 
either by attempting to enforce flow control, or by letting the terminal and 
terminal driver handle it. In this example, the terminal and terminal 
driver handle flow control; the driver sends XON, XOFF, or BELL 
characters to the terminal as necessary. 


One of the six I/O buffers is permanently reserved as the terminal read 
buffer. This buffer is passed directly to the terminal read $QIO. This 
eliminates having to move data that is read from the terminal into the 
read buffer. The other five buffers are placed in a queue and are allocated 
and deallocated as needed. This pool of buffers reserves the first two 
longwords to be used as queue headers and traditional IOSBs. The third 
longword and the I/O status longwords are used by the pseudoterminal 
driver. 
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Example 9-1 Sample Pseudocode for Pseudoterminal Driver Program 





/* 
*k* 
Kk 
*x* 
K* 
Kk 
Kk 
K* 
Kk 
*K* 
xk 
Kk 
k* 
kK 


oid 


Main Routine 


Function: Intitializes the environment and then hibernates, waiting 

to be awakened. When awakened, the program checks to see whether it 

is exiting, or whether more log data is available. If more data is 
available, the data is appended to the current log record and checked 
to see whether a log record should be written. A log record is written 
either when maxbuf characters are in the log buffer, 

or when it finds a <CR><LF> character pair. The algorithm 

allows an unlimited number of <NULL> fill characters to occur 

between the <CR> and the <LF>. If the program is 

exiting, it closes the log file, deletes the pseudoterminal, resets the 
terminal, and exits. 


Initialize environments (This includes creating pseudoterminal, the log file 


Le 


and starting up the subprocess.) 


(Initialization OK) Then 
Do 
while (I/O buffer to log) 
Data size = number of bytes in I/O buff 
For all data in I/O buffer 
If (cr_seen) Then 
If (current char == <LF>) Then 
write current log buffer 
reset cr_seen 
point to start of log buffer 
Else if (current char != <NULL>) Then 
insert <CR> and current char into log buffer 
move log buffer ptr over 2 characters 
reset cr_seen 
Endif 
Else if (current character != <CR>) Then 
insert character into log buffer 
move log buffer ptr over 1 character 
Else 
set cr_seen 
Endif 


If (log buffer ptr >= IOCSGW_MAX-48) Then 
write log buffer 
reset log buffer pointer 
reset cr_seen 
Endif 
Endloop 
Free I/O buffer call free_io buffers 
Endwhile 
If (not exiting) Then 
Wait for more to do call SYSSHIBER 
Endif 
Until ((exiting) and (no I/O buffers to log) ) 





(continued on next page) 
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Example 9-1 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program 





close log file 
If ((close failed) and (exit reason is SS$_NORMAL)) Then 
set exit to status to failure reason 
Endif 
If (subprocess still running) Then 
call SYSSFORCEX to run down the subprocess 
Endif 
call PTDSCANCEL to flush all pending pseudoterminal read requests 
call SYSSCANCEL to flush all terminal requests 
call PTDSDELETE to delete the pseudoterminal 
If ((delete failed) and (exit reason is SS$ NORMAL)) Then 
set exit to status to failure reason 
Endif 
reset terminal to startup condition using SYSSQIOW 
If ((terminal reset failed) and (exit reason is SS$ NORMAL)) Then 
exit to status to failure reason 
Endif 
Endif 
call LIBSSIGNAL and report exit reason 
Bxit 
/* 
Kk 
** Initialization Code 
*xx* 
** Function: This routine sets the terminal characteristics, creates the 
*k pseudoterminal, starts up the subprocess, and opens the log file. If 
** any of these steps fail, the program undoes any steps already done and 


x** returns to the main routine. 
kk 


ey 


read the maximum buffer size from IOCSGW_MAXBUF 
Assign a channel to SYSSINPUT 
If (assign ok) Then 
Read the terminal characteristics from the terminal 
If (read of terminal characteristics ok) Then 
Open log file with maximum record size of IOCSGW_MAXBUF 
If (open ok) Then 
Create the pseudoterminal with characteristics of terminal 
If (create ok) then 
Place 4 of the buffers on the queue of free I/O buffers 
Copy terminal characteristics and modify them to NOECHO and PASTHRU 
Set the terminal characteristics use modified value 
If (set ok) Then 
Get device name of pseudoterminal use SYSSGETDVI 
If (get ok) Then 
Create subprocess 
If (create ok) Then 
Enable XON, XOFF, BELL, SET_LINE event notification ASTs 
If (AST setup OK) Then 
Call PTDSREAD to start reading from the pseudoterminal 
ASTADR = ft_read_ast 
ASTPRM = buffer address 
READBUF = I/O buffer + 8 
READBUF_LEN = 500 
If (read ok) Then 
Call SYSSQIO and read a single character from the 
keyboard ASTADR = kbd_read_ast 





(continued on next page) 
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Example 9-1 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program 


If (read failed) Then 
Call PTDSCANCEL to flush queued pseudoterminal read 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Close log file and delete it 
Endif 
Else 
Close log file and delete it 
Endif 
Endif 
Endif 


Endif 


/* 
x* 
*xx* 
Kk 
kk 
K* 
K* 
** 
kk 
*x* 
x* 
Kk 
Kk 
Kk 


Bd 


kbd_read_ast 


Function: This routine is called every time data is read from the terminal. 
If the program is exiting, then the routine exits without restarting the 
read. The character read is checked to see if the terminate processing 
character Ctrl\ was entered. If the terminate processing character was 
entered, the exiting state is set and a SYSSWAKE is issued to start the 
main routine. Now an attempt is made to obtain an I/O buffer in which 

to store echoed output. If an I/O buffer is unavailable, a simple 
PTDSWRITE is issued; a PTDS$WRITE with echo is issued if a buffer is 
available. If the write completes successfully, another read is issued 

to the keyboard. 


(continued on next page) 
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Example 9~—1 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program 


If (not exiting) Then 
If (read ok) Then 
Search input data for Ctrl\ 
Allocate a read buffer call allocate _io buffer 
If (got a buffer) Then 
Call PTDSWRITE to write characters to pseudoterminal 
ASTADR = ft_echo_ast 
ASTPRM = allocated I/O buffer 
WRTBUF = read I/O buffer 
WRTIBUF_LEN = number of characters read 
ECHOBUF = allocated I/O buffer 
ECHOBUF_LEN = 500 
Else 
Call PTDSWRITE to write characters to pseudoterminal 
WRTBUF = read I/O buffer 
WRIBUF_LEN = number of characters read 
Endif 
If (write setup ok) 
If ((write status is ok) or (write status is SS$_DATALOST) ) 
Issue another single character read to terminal with 
ASTADR = kbd_read_ast, with data going to read I/O buffer 
If (read setup failed) Then 
Set exit flag 
Set exiting reason to SS$ NORMAL 
Endif 
Else 
Set exit flag 
Set exiting reason to SS$ NORMAL 
Endif 
Elise 
Set exit flag 
Set exiting reason to SS$ NORMAL 
Endif 
Else 
Set exit flag 
Set exiting reason to read failure status 
Endif 
If (exiting) Then 
Wake the mainline call SYSSWAKE 
Endif 
Endif 


(continued on next page) 
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/* 

** terminal output_ast 

kk 

** Function: This routine is called every time an I/O buffer is written 
** to the terminal. If the terminal write request completes successfully, 
** it inserts the I/O buffer into the queue of I/O buffers to be logged. 
**k If the I/O buffer is the only entry on the queue, it issues a SYSSWAKE 
**k to start the main routine. To prevent spurious wake requests, 

** SYSSWAKE is not issued if multiple entries are already on 

** the queue. If a terminal write error occurs, the routine sets the 


** exit flag and wakes the main routine. 
xk 


aes 
If (terminal write completed ok) Then 

insert I/O buffer onto logging queue 

If (this is only entry on queue) Then 

wake the mainline call SYSSWAKE 

Endif 
Else 

set exit flag 

set exiting reason to terminal write error reason 

wake the mainline call SYSSWAKE 
Endif 
/* 
kk 
ee EE Bead ast 
xK* 
** Function: This routine is called when a pseudoterminal read request 
** completes. It writes the buffer to the terminal and attempts to start 
** another read from the pseudoterminal. If the program is not exiting, 
** this routine writes the buffer to the terminal and does not start another 
** pseudoterminal read. 


If (not exiting) 
If (Pseudoterminal read ok) Then 
write buffer to the terminal ASTADR = terminal_output_ast 
If (write setup ok) Then 
Allocate another read buffer call allocate_io buffer 
If (got a buffer) Then 
Call PTDSREAD to restart reads from the pseudoterminal. 
ASTADR = ft_read_ast 
ASTPRM = buffer address 
READBUF = I/O buffer + 8 
READBUF_LEN = 500 
If (read setup failed) Then 
Set exit flag 
Set exiting reason to read failure reason 
Wake the mainline call SYSSWAKE 
Endif 
Else 
Set read stopped flag 
Endif 
Else 
Set exit flag 
Set exiting reason to terminal write failure reason 
Wake the mainline call SYSSWAKE 
Endif 





(continued on next page) 
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Example 9-1 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program 





Else 
Set exit flag 
Set exiting reason to terminal read failure reason 
Wake the mainline call SYSS$WAKE 
Endif 
Endif 
/* 
kk 
£*, LC ECHO -eSt 
Kx 
** Function: This routine is called if a write to the pseudoterminal used 
** an ECHO buffer. If any data was echoed, the output is written to the 
** terminal. If no data was echoed, the I/O buffer is freed so it can be 


** used later. If the program is exiting, this routine exits. 
K* 


ef: 
If (not exiting) Then 
If (ECHO buffer has data) Then 
Write the buffer to the terminal with ASTADR = terminal_output_ast 
If (error setting up write) Then 
Set exit flag 
Set exiting reason to write failure reason 
Wake mainline call SYSSWAKE 
Endif 
Else 
Free I/O buffer call free_io buffers 
Endif 
Endif 
/* 


“*® £ree- io buffers 


*k Function: This routine places a free I/O buffer on the queue of available 
** I/O buffers. It also restarts any stopped read operations from the 

*k pseudoterminals. This routine disables AST delivery while it is running 
** in order to synchronize reading and resetting the read stopped flag. 


If (not exiting) Then 
Disable AST deliver using SYSSSETAST 
If (Pseudoterminal reads not stopped) Then 
Insert I/O buffer on the interlocked queue of free I/O buffers 
Else 
Call PTDSREAD to restart reads from the pseudoterminal. 
ASTADR = ft_read_ast 
ASTPRM buffer address 
READBUF = I/O buffer + 8 
READBUF_LEN = 500 
If (no error starting read) Then 
Clear read stopped flag 
Else 
Set exit flag 
Set exit reason to read setup reason 
Endif 
Endif 
Enable AST delivery using SYSSSETAST 
Endif 


(continued on next page) 
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/* 
x* 
kk 
kK* 
xx 
Kx 
K* 
K* 
*/ 
LE 


allocate_io buffer 


Function: This routine obtains a free I/O buffer from the queue of 
available I/O buffers. If the program is exiting, this routine 
returns an SS$_FORCEDEXIT error. 


(not exiting) Then 
remove a I/O buffer from the interlocked queue of I/O buffers 
If (queue empty) Then ; 

exit with reason LIB$_QUEWASEMP 


else 


exit with reason SS$_FORCEDEXIT 


Endif 


/* 
KK 
aK 
** 
aK 
** 
x 
* 
tf 
Le 


subprocess_exit 


Function: This routine is called when the subprocess has completed 

and exited. This routine checks whether the program is already exiting. 
If not, then the routine indicates that the program is exiting and wakes 
up the main program. 


(not exiting) Then 

indicate subprocess no longer running 
set exit status to SS$ NORMAL 
indicate exiting 

call SYSSWAKE to start up main loop 


Endif 


/* 
K* 
K* 
K* 
zk* 
K* 
K* 
Kk 


xon_ast 


Function: This routine is called for the pseudoterminal driver to signal 
that it is ready to accept keyboard input. The routine attempts to send 
an XON character to the terminal by sending XON DCl using SYSSQIO. 

If the attempt fails, it is not retried. 


#7 
If (not exiting) Then 
call SYSSQIO to send a <DC1l> character to the terminal 
Endif 
/* 
we Dell .ast 
Kk : 
** Function: This routine is called when the pseudoterminal driver wants 
** to warn the user to stop sending keyboard data. The routine attempts 
*k* to ring the terminal bell by sending the BELL character to the terminal 
** using SYSSQIO. If the attempt fails, it is not retried. 
Kk 
*/ 
If (not exiting) Then 
call SYSS$SQIO to send a <BELL> character to the terminal 
Endif 





(continued on next page) 
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/* 
ee XOLL ast 
Ak 
** Function: This routine is called when the pseudoterminal driver wants to 
** signal that it will stop accepting keyboard input. The routine attempts 
** to send an XOFF character to the terminal by sending XOFF DC3 to the 
** terminal using SYSSQIO. If the attempt fails, it is not retried. 
Kk 
yf 
If (not exiting) Then 
call SYSSQIO to send a <DC3> character to the terminal 
Endif 
/* 
e* #60 line ast 
K* 
** Function: This routine is called when the pseudoterminal device 
** characteristics change. The routine reads the current pseudoterminal 
** characteristics, changes the characteristics to set PASTHRU and NOECHO, 
** and applies the characteristics to the input terminal. If the attempt 


*k to alter the terminal characteristics fails, it is not retried. 
K* 


i 
If (not exiting) Then 
call SYSSQIOW to read the pseudoterminals characteristics 
If (not error) Then 
Set the alter the just read characteristics to have PASTHRU and NOECHO 
attributes 
call SYSSQIO to set the terminal characteristics. 
Endif 
Endif 
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1 0 Shadow-Set Virtual Unit Driver 


10.1 


Introduction 


Note: 


This chapter describes the use of the shadow-set virtual unit driver 
(SHDRIVER) and provides an overview of VMS Phase II Volume 
Shadowing. For more detailed information on VMS Phase II Volume 
Shadowing, see the VMS Volume Shadowing Manual. 





VMS Phase II Volume Shadowing allows shadowing on the same 
configurations as phase I volume shadowing described in the VAX Volume 
Shadowing Manual. In addition, phase II supports clusterwide shadowing 
of all MSCP (mass storage control protocol) compliant DSA (DIGITAL 
Storage Architecture) disks that have the same physical geometry, on a 
single system or located anywhere in a VAXcluster system. 


Phase II volume shadowing supports clusterwide shadowing of all DSA 
devices. Phase II is not limited to HSC (hierarchical storage controller) 
disks, but extends volume shadowing capabilities to all DSA disks 
including those on local adapters, all DSSI (DIGITAL Small Systems 
Interconnect) RF-series disk devices on any VAX computer, all interfaces 
(computer interconnect [CI], Ethernet, mixed-interconnect), and across 
VMS MSCP servers. 


SHDRIVER is the driver that controls the virtual unit functions described 
in Section 10.4. 


Like phase I shadowing, any given phase II shadow set can have a 
maximum of three shadow set members. Phase II shadowing also 
provides more flexibility regarding shadow set membership because phase 
II shadowing does not limit the number of shadow sets or shadow set 
members for each controller or pair of controllers. 


Phase II volume shadowing places no restrictions on the total 
number of shadow set members; however, interconnect or adapter 
bandwidths during shadow-set copy operations might force 
shadow set limits. 


Other phase II volume shadowing features include: 


¢ Controller independence. Shadow set members can be located on any 
node in a VAXcluster system that has volume shadowing enabled. 


e Clusterwide, homogeneous shadow-set maintenance functions. 
e Ability to survive controller, disk, and media failures transparently. 
e Shadowing functions do not affect application I/O. 


¢ Coexistence with phase I volume shadowing. Shadow sets are 
differentiated by virtual-unit name format. 
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10.2 Phase | and Phase II Compatibility 





10.3 Configurations 


You can use both phase I and phase II shadowing on a standalone system 
or a VAXcluster system. For example, you can use phase I shadowing on 
one node and phase II shadowing on another node. Note, however, that 
members in a given shadow set must be either phase I or phase II; they 
cannot be of mixed types. Also, using two types of shadowing on the same 
system complicates system management because: 


¢ The method of naming virtual units differs between the phase I and 
phase IT products. 


¢ The SYSGEN parameter settings for a given node must be set to the 
shadowing mode you choose to use for that node. 


Although the underlying design of phase IJ volume shadowing is different 
from that of phase I, the user interface for the two shadowing products 
is very similar. The VMS Mount Utility commands, SHOW commands, 
and system services for both shadowing products are very similar, and 
application I/O semantics for shadow set manipulation is the same for 
both. Phase II shadowing supports a new MOUNT qualifier that is useful 
for automating the rebuilding of former shadow sets. 


For discussions of phase II SYSGEN parameters, booting, system 
upgrades, and migration and compatibility considerations, see the VMS 
Volume Shadowing Manual. 


VMS Phase II Volume Shadowing does not depend on specific hardware 
in order to operate. All shadowing functions can be performed on VAX 
computers running the VMS operating system. Shadowing capabilities 
are supported on all VMS MSCP devices, including RF devices, and on all 
types of DSA-compliant disks. Shadow set members must have the same 
physical geometry (that is, the same number of identical logical blocks 
[LBNs]), and members can be located anywhere in a VAXcluster system. 


10.3.1 Processors and Controllers 
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Volume shadowing requires a minimum of one VAX computer, one MSCP- 
compliant mass storage controller, and at least two DSA disk drives and 
volumes. 


Digital provides shadowing capabilities on: 
e All DSA and MSCP-compliant drives: 
— On the same local controller 
— On different local controllers 


— On controllers local to different VMS hosts and to VMS MSCP 
served to the VAXcluster system over CI, Ethernet, DSSI, and 
mixed-interconnect configurations 
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¢ DSA- and MSCP-compliant integrated storage elements (ISEs) on the 
same DSSI as the VMS hosts 


* DSA- and MSCP-compliant ISEs that are VMS MSCP served to the 
VAXcluster system on the same or different DSSIs 


e All DSA disks having the same physical geometry 
e All interfaces for DSA devices 


Devices that cannot be shadowed include: 
¢ Small Computer System Interface (SCSI) devices 
¢ MicroVAX 2000 RD disks 


¢ Pre-DSA disk devices (such as MASSBUS, RKO07, RLO2, RPO6G, and 
RP07) 


Table 10—1 lists the hardware supported by VMS Volume Shadowing. 


Table 10-1 Hardware Devices That Support Volume Shadowing 


Disk Controllers and Adapters 


HSC40, HSC50, HSC70 
KDA50 

KDB50 

KDM70 

RQDX2, RQDXx3' 
UDA50 


Disks 


ESE20 

RA60, RA70, RA80, RA81, RA82, RA90, RA92 

RD51, RD52, RD53, RD54 (when connected to RQDX) 
RF30, RF31, RF71, RF72 


1Shadow set members should be on different RQDX controllers. 


10.3.2 Compatible Disk Drives and Volumes 


Volume shadowing requires compatibility among the physical units (disk 
drives and volumes) that form a shadow set. For instance: 


¢ Units must have the same geometry, including the same number of 
sectors per track, the same number of tracks per cylinder, and the 
same number of cylinders per volume. 


¢ Units and controllers must conform to DSA and MSCP. 
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10.4.1 
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¢ Units should not have hardware write protection enabled. Hardware 
write protection stops the volume shadowing software from 
maintaining identical volumes. 





Driver Functions 


This section describes the major virtual unit functions supported by 
SHDRIVER. In addition to the virtual unit functions described in this 
section, SHDRIVER supports all VMS disk functions. SHDRIVER receives 
QIO operations from application programs and is a client of the disk class 
drivers DUDRIVER and DSDRIVER. Applications access the shadow set 
as they would access a standard VMS disk. 


Table 10-2 summarizes the major SHDRIVER functions. The subsections 
that follow describe these functions in detail. 


Table 10-2 Functions of the Shadow Set Virtual Unit Driver 


Function Description 
CRESHAD Creates a virtual unit 
ADDSHAD Evaluates a physical member and adds members 


COPYSHAD Triggers and controls copy operations 

REMSHAD Removes a physical member 

AVAILABLE Virtual unit dissolution 

SENSECHAR _ Verifies shadow set status 

READ Directs I/O to a physical member 

WRITE Propagates a write operation to all physical members 


CRESHAD 


The CRESHAD function creates a virtual unit, and establishes a 
clusterwide lock. This function is internal and can be issued only by 
the MOUNT utility, from either DCL or the $MOUNT system service. 


The function code is: 
I10$_CRESHAD 


10$_CRESHAD takes the function modifier IO$M_EXISTS. When 
IO$M_EXISTS is specified, the virtual unit exists in the cluster and 
I0$_CRESHAD creates an identical, multimember set. If IO$M_EXISTS 
is not set, the shadow set does not exist yet and IO$_CRESHAD creates a 
single member shadow set. 


IO0$_CRESHAD also validates the shadow-set virtual unit, enables 
distributed locking protocols, and creates or updates the unit control 
block (UCB) and shadow set (SHAD) structures for the virtual unit. 
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The following are the device-dependent or function-dependent arguments 
for IO$_CRESHAD. (Note that these arguments are internal; they cannot 
be accessed by user programs.) 


¢ P1—The address of the shadow-set virtual unit name string, or zero. 


e p2—If P1 does not equal zero, this parameter is the size of the shadow 
set virtual unit name string. If P1 equals zero, this parameter is the 
unit number of the shadow-set virtual unit. 


¢ P3—The storage control block (SCB) logical block number (LBN) from 
the first member listed in the MOUNT command. 


IO$_CRESHAD can return the following status codes: 
¢ SS$_NORMAL—Normal successful completion. 


e SS$ _ACCVIO—An access violation occurred because the shadow-set 
virtual unit name string is not readable. 


e S$S$_INSFMEM—Not enough memory exists to allocate the UCB or 
SHAD structure. 


e SS$ IVDEVNAM—tThe unit number for the shadow set virtual unit is © 
greater than 9999. 


¢ SS$ INCSHAMEM—tThe specified shadow set member cannot be a 
member of the existing shadow set because it is the quorum disk or is 
of incompatible geometry. 


e SS$_DUPINIT—The specified shadow set already exists. 


The ADDSHAD function is an internal control function that validates 
the channel number and unit control block (UCB) address for a proposed 
shadow-set virtual unit member. This function also validates the specified 
copy-type information for the shadow-set virtual unit member and 
performs a clusterwide update. IO$_ADDSHAD then adds the member to 
the shadow set by updating the disk data structure and notifying other 
shadow set members. 


The function code is: 


I0$_ADDSHAD 
10$_ADDSHAD takes no function modifiers. 


The following are the device-dependent or function-dependent arguments 
for IO$¢_ADDSHAD: 


¢ P2—The channel number assigned to the proposed shadow set member 
¢ P3—The copy type (full or merge) of the member 

I0$_ADDSHAD can return the following status codes: 

¢ SS$NORMAL—Normal successful completion. 

e SS$_BADPARAM—The UCB is not a virtual unit UCB. 
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10.4.3 COPYSHAD 


10-6 


e SS$ ILLIOFUNC—The unit is not a shadow set virtual unit, or P2 
points to a shadow set virtual unit. 


¢ SS$ NOPRIV—The user has no access to the channel specified in P2. 
e §S$ IVCHAN—The channel number specified in P2 is invalid. 
e SS$_IVMODE—The copy-type mode specified in P8 is invalid. 


e SS$ INSFMEM—Insufficient memory is available to allocate the 
shadow set member VCB, and resource wait mode is disabled. 


¢ SS$_INCSHAMEM—tThe physical unit cannot be added to the shadow 
set for one of the following reasons: 


— The shadow set is already fully populated. 
— The device being added is not a VMS MSCP device. 


— The geometry or hardware properties of the physical unit do not 
match those of the other shadow set members. 


— The proposed shadow set member is the quorum disk. 


— The physical unit is already a member of another shadow set. 


The COPYSHAD function triggers and controls copy operations. It should 
be issued only by the MOUNT utility or the shadow server process. 


The function code is: 
10$_COPYSHAD 


I0$_COPYSHAD takes the following function modifiers: 


¢ JO$M_COPYOP—Requests a copy operation. This modifier is issued 
by the shadow server when the server requests a copy operation. 


¢ IO$M_STEPOVER—Provides for protection of the volume storage 
control block (SCB) during copy operations. 


The following are the device-dependent or function-dependent arguments 
for IO$_COPYSHAD: 


¢ P2—The request byte count 
¢ P3—The starting LBN 
e P4—The copy mode 


10$_COPYSHAD can return an SS$ ILLIOFUNC status for one of the 
following reasons: 


¢ A COPY I/O command was issued by a process other than the shadow 
server. 


e Another copy operation was attempted while a copy operation was 
already in progress. 


10.4.4 REMSHAD 
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¢ A COPY I/O command was issued while a copy operation was not in 
progress. 


Figure 10-1 illustrates the I/O status block returned for copy operations. 
Figure 10-1 1|/O Status Block for Copy Operations 


Stream Copy LBN 
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I0$_COPYSHAD receives copy initiation I/O request packets (IRPs) during 
a copy operation. IO$_COPYSHAD then performs the full or merge copy 
operation; upon completion, IO$_COPYSHAD receives I0$_COPYSHAD 
IRPs from the shadow server. A SS$_RESET message is returned if a 
copy-state reconciliation is needed because the copy initialization process 
has triggered a state change. The shadow server then issues an 
I0$_SENSECHAR function (see Section 10.4.6). 


The REMSHAD function removes a device from a shadow set virtual unit. 
The REMSHAD function can be issued only by the $DISMOUNT system 
service to a physical device. 


The function code is: 
I0$_REMSHAD 


The I0$_REMSHAD function takes no modifiers. 


IO$_REMSHAD verifies that the unit to be removed is a valid physical 
volume and a member of a shadow set. If either of these conditions 

is not true, SH$REMSHAD _FDT returns an SS$_ILLIOFUNC status. 
I0$_REMSHAD then removes the specified device from a shadow set by 
breaking the links between the device UCB and the other shadow-set 
data structures; clears device status fields; and removes references to the 
device from the device array in the SHAD structure. IO$_REMSHAD also 
updates the SCBs of disks that remain in the shadow set after changes are 
made to the local data structures. 


If the shadow set has too few members to remove one, a SS$_BADPARAM 
status code is returned. Otherwise, SH$START_REMSHAD returns 
SS$_NORMAL to indicate a normal successful completion. Upon 
successful completion, IO$_REMSHAD notifies the remaining shadow 

set members. 
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10.4.5 AVAILABLE 


10.4.6 SENSECHAR 
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The AVAILABLE function makes a virtual unit available by eliminating 
local control of the unit. AVAILABLE also makes the necessary changes to 
the local shadowing I/O database for disassembling the shadow set on the 
node, and releases cluster shadowing locks. 


The function code is: 
10$ AVAILABLE 


The IO$_AVAILABLE function takes no modifiers. 


10$ AVAILABLE first unloads the FDT (function decision table) for 
shadowing. If the specified unit is a member of a shadow set, or if 
IO$V_DISSOLVE is present for a physical unit, IO$_AVAILABLE returns 
an SS$_ILLIOFUNC status code. IO$ AVAILABLE then makes all 
changes to the local shadowing I/O database that are necessary to 
dismount the shadow set on the node. 


The SENSECHAR function verifies the existence and membership status 
of a shadow set. 


The function code is: 


10$_SENSECHAR 


This function code takes the following function modifiers: 
¢ IO$M_SHADOW 
¢ IO$M_COPYOP 


When the IO$¢M_SHADOW modifier is specified, the IO$_SENSECHAR 
verifies the presence of a properly prepared VCB, initializes the VCB 

if necessary, and passes the request to the driver start I/O routine. If 
the IO$M_SHADOW modifier is not specified, the routine returns to the 
FDT processing loop. An SS$_BADPARAM status code is returned if the 
shadow-set virtual unit VCB is not present or is set up incorrectly. 


IO$_SENSECHAR processing then begins. If specified, the modifiers 
IO$M_SHADOW and IO$M_COPYOP are used by the shadow server 
to determine whether or not to do any more copy operations before 
deallocating its resources. 


10$_SENSECHAR then ensures that the VCB address information in the 
SHAD data structure is up to date. 


Finally, IO$_SENSECHAR determines whether any copy requests were 
previously suspended. A status code of SS$_ NORMAL indicates that no 
copy operations were suspended. A status code of SS$_RESET indicates 
that copy operations are to continue; the LBN and mode data are supplied 
in the I/O status block, as shown in Figure 10-2. 
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Figure 10-2 I/O Status Block for Copy Information 


New Copy Mode SS$_ RESET 
New Copy LBN 
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10.4.7 Read and Write Functions 


With just minor changes, the read and write functions for SHDRIVER 
operate the same as for the disk class driver (see Sections 3.4.1 and 3.4.2). 


During an SHDRIVER read operation, the VAX host directs the read to 
the member volume with the shortest path. 


During a write operation, SHDRIVER directs the write to each member 
volume. The write operations for each member volume usually proceed 
in parallel; the virtual unit write operation terminates when all writes 
have completed. The write function for SHDRIVER takes the IO$M_FC_ 
VUEX function modifier; this modifier should not be used by application 
programs. 


The read and write SHDRIVER functions, as well as all user functions, are 
issued by user programs. All other SHDRIVER functions are invoked by 
MOUNT and DISMOUNT commands, or the $MOUNT and $DISMOUNT 
system services. 





10.5 Error Processing 


Shadow set recovery and repair are handled by volume processing, which 
replaces mount verification for shadow sets. The main difference in phase 
II shadowing is that membership failure decisions are made by the VAX 
hosts. Device errors that result in inaccessibility of physical member units 
first utilize the class driver’s connection walking algorithm. If that fails, a 
local decision is made on the shadow set membership. The rules are: 


e If some, but not all, members of the set are accessible, then the local 
node sequentially adjusts the membership and notifies the other hosts. 


¢ Ifno members are accessible, no modifications to the set membership 
are made. 


There are two types of volume processing: active and passive. Active 
volume processing handles error processing on a local node. Triggered 

by a failed I/O operation, active volume processing also controls mount 
verification functions, member removal, and failover. Passive volume 
processing is triggered by lock messages or by a cluster event. Passive 
volume processing revalidates shadow set membership, ensures that the 
shadow set reflects changes made outside the shadow set, and handles the 
following functions: 


¢ Member additions from other nodes 
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¢ Member removals from other nodes 
e A new node mounting the shadow set 
¢ Anode dismounting the shadow set 


e A system crash on a node that has the shadow set mounted 


For more information, see the VMS Volume Shadowing Manual. 
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11 Using the VMS Generic SCSI Class Driver 


This chapter describes the use of the VMS Generic Small Computer 
Systems Interface (SCSI class driver. 





11.1 Overview of SCSI 


The American National Standard for information systems—Small 
Computer System Interface—2 (SCSI-2) specification defines mechanical, 
electrical and functional requirements for connecting small computers to 
a wide variety of intelligent devices, such as rigid disks, flexible disks, 
magnetic tape devices, printers, optical disks, and scanners. It specifies 
standard electrical bus signals, timing, and protocol, as well as a standard 
packet interface for sending commands to devices on the SCSI bus. 


Certain VAXstation and MicroVAX systems employ the SCSI bus as an 
I/O bus. For these systems, Digital offers SCSI-compliant disk and tape 
drives, such as the RZ55 300MB read/write disk, the RRD40 600MB 
compact disk, and the TZK50 95MB streaming tape drive. The VMS 
operating system also allows non-Digital-supplied devices including disk 
drives, tape drives, and scanners to be connected to the SCSI bus of such a 
system. 


SCSI has been widely adopted by manufacturers for a variety of peripheral 
devices. However, because the ANSI SCSI standard is broad in scope, not 
all devices that implement its specifications can fully interrelate on the 
bus. Digital fully supports SCSI-compliant equipment sold or supplied 

by Digital. Proper operation of products not sold or supplied by Digital 
cannot be assured. 


For more information, refer to the following documents: 


¢ American National Standard for Information Systems—Small 
Computer System Interface—2 (SCSI-2) specification (X3T9.2/86-109) 


The SCSI-2 specification is a draft of a proposed standard. Until it 

is finally approved, copies of this document may be purchased from: 
Global Engineering Documents, 2805 McGaw, Irvine, California 92714, 
United States; or (800) 854-7179 or (714) 261-1455. Please refer to 
document X3.131—198X. 


¢ American National Standard for Information Systems—Small 
Computer System Interface specification (X3.131-1986) 


Copies of this document may be obtained from: American National 
Standards Institute, Inc., 1430 Broadway, New York, New York, 10018. 
This document is now known as the SCSI-1 standard. 
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Digital publishes two additional documents to help third-party vendors 
prepare SCSI peripherals and peripheral software for use with Digital’s 
workstations and MicroVAX systems. 


¢ The Small Computer System Interface: An Overview 
(EK-SCSISOV—001) provides a general description of Digital’s SCSI 
third-party support program. 


¢ The Small Computer System Interface: A Developer’s Guide 
(EK-SCSIS—SP-—001) presents the details of Digital’s implementation 
of SCSI within its operating systems. 


11.2 VMS SCSI Class/Port Architecture 


The VMS operating system employs a class/port driver architecture to 
communicate with devices on the SCSI bus. The class/port design allows 
the responsibilities for communication between the operating system and 
the device to be cleanly divided between two separate driver modules (see 
Figure 11-1). 


The SCSI port driver transmits and receives SCSI commands and data. It 
knows the details of transmitting data from the local processor’s SCSI port 
hardware across the SCSI bus. Although it understands SCSI bus phases, 
protocol, and timing, it has no knowledge of which SCSI commands the 
device supports, what status messages it returns, or the format of the 
packets in which this information is delivered. Strictly speaking, the port 
driver is a communications path. When directed by a SCSI class driver, 
the port driver forwards commands and data from the class driver onto 
the SCSI bus to the device. On any given MicroVAX/VAXstation system, 

a single SCSI port driver handles bus-level communications for all SCSI 
class drivers that may exist on the system. 


The SCSI class driver acts as an interface between the user and the SCSI 
port, translating an I/O function as specified in a user’s $QIO request 

to a SCSI command targeted to a device on the SCSI bus. Although the 
class driver knows about SCSI command descriptor buffers, status codes, 
and data, it has no knowledge of underlying bus protocols or hardware, 
command transmission, bus phases, timing, or messages. A single class 
driver can run on any given MicroVAX/VAXstation system, in conjunction 
with the SCSI port driver that supports that system. The VMS operating 
system supplies a standard SCSI disk class driver and a standard SCSI 
tape class driver to support its disk and tape SCSI devices. 


11.3 Overview of the VMS Generic SCSI Class Driver 
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The VMS generic SCSI class driver provides a mechanism by which an 
application program can control a non-Digital-supplied SCSI device that 
cannot be controlled by the standard VMS disk and tape class drivers. 
By means of a Queue I/O Request ($QIO) system service call, a program 
can pass to the generic SCSI class driver a preformatted SCSI command 
descriptor block. The generic SCSI class driver, in conjunction with the 
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Figure 11-1 VMS SCSI Class/Port Interface 
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standard VMS SCSI port driver, delivers this SCSI command to the device, 
manages any transfer of data from the device to a user buffer, and returns 
SCSI status to the application. 


In effect, an application using the generic SCSI class driver implements 
details of device control usually managed within device driver code. 
The programmer of such an application must understand which SCSI 
commands the device supports and which SCSI status values the device 
returns. The programmer must also be aware of the device’s timeout 
requirements, data transfer capabilities, and command retry behavior. 


The application program sets up the characteristics of the connection the 
generic SCSI class driver uses when delivering commands to, exchanging 
data with, and receiving status from the device. The program associates 
each I/O operation the device can perform with a specific SCSI command. 
When it receives a request for a particular operation, the application 
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program creates the specific command descriptor block that, when passed 
to the device, causes it to perform that operation. 


The application initiates all transactions to the SCSI device by means of 
a $QIO call to the generic SCSI class driver, supplying the address and 
length of the SCSI command descriptor block, plus the parameters of any 
data transfer operation, in the call. When the transaction completes and 
the application program regains control, it interprets the returned status 
value, processes any returned data, and services any failure. To avoid 
conflicts with other applications accessing the same device, an application 
may need to explicitly allocate the device. 


Because the generic SCSI class driver has no knowledge of specific device 
errors, it neither logs device errors nor implements error recovery. An 
application using the driver must manage device-specific errors itself. To 
service an error returned on a single transaction, the application must 
issue additional $QIO requests and initiate further transactions to the 
device. If more precise or more efficient error recovery is required for a 
device, the developer should consider writing a third-party SCSI class 
driver, as described in VMS Device Support Manual. A third-party SCSI 
class driver can log errors associated with device activity by using the 
method described in the VMS Device Support Manual. 


A third-party class driver is the only means of supporting devices that 
themselves generate transactions on the SCSI bus, such as notification 
of a device selection event to the host processor. See the description 
of asynchronous event notification (AEN) in the VMS Device Support 
Manual. 


Figure 11-2 illustrates the flow of a $QIO request through the generic 
SCSI class driver and the port driver. 


When direct access to a target device on the SCSI bus is required, 
the generic SCSI class driver is loaded for that device, as described 
in Section 11.6. An application program using the generic class driver 
performs the following tasks to issue a command to the target device: 


1 Calls the Assign I/O Channel ($ASSIGN) system service to assign a 
channel to the generic SCSI class driver, and allocate the device for 
the application’s exclusive use 


Formats a SCSI command descriptor block 
Formats any data to be transferred to the device 


Calls the Queue I/O Request ($QIO) system service to request the 
generic SCSI class driver to send the SCSI command descriptor block 
to the port driver 


5 Upon completion of the I/O request, interprets the SCSI status byte 
and any data returned from the target device 
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Figure 11-2 Generic SCSI Class Driver Flow 
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These operations are described in subsequent sections. 


Note: Because incorrect or malicious use of the generic SCSI class 


driver can result in SCSI bus hangs and lead to SCSI bus resets, 
DIAGNOSE and PHY_IO or LOG_IO privileges are required to 
access the driver. An application program can be designed in such 
a way as to filter user I/O requests, thus allowing nonprivileged 
users access to some device functions. 


11.4 Accessing the VMS Generic SCSI Class Driver 


Interactive commands and procedure calls can use the VMS generic SCSI 
class driver to access devices on the SCSI bus. However, it is unlikely that 
a user application would access a device on the SCSI bus by directly using 
the $QIO interface of the generic SCSI class driver. First of all, any user 
process directly using the $QIO interface would require DIAGNOSE and 
PHY_IO or LOG_IO privileges. Under normal circumstances, it would 

be a system security risk to grant DIAGNOSE and PHY_IO or LOG_IO 
privileges to many system users. Secondly, it would be cumbersome for 
end users of the device to identify, format, and issue SCSI commands to 
the device. Rather, it would be more efficient to develop an interface that 
hides these details. 


A utility program, installed with the DIAGNOSE and PHY_IO or LOG_IO 
privileges, can provide nonprivileged users with a command line interface 
to a SCSI device. The utility translates interactive commands provided 
by the user into the appropriate set of SCSI commands and sends them 
to the device using the $QIO interface provided by the generic SCSI class 
driver. The utility checks user commands to ensure that only valid SCSI 
commands are sent to the device. See the Guide to VMS Programming 
Resources and the VMS Install Utility Manual for information about 
installing images with privileges. 


A privileged shareable image can provide system applications with a 
procedure interface to a SCSI device. The image contains a set of 
procedures that translate operations specified by the caller into the 
appropriate set of SCSI commands. The SCSI commands are sent to the 
device through the $QIO interface of the generic SCSI class driver. The 
privileged shareable image checks its caller’s parameters to ensure that 
only valid SCSI commands are sent to the device. See the Introduction to 
VMS System Services for information about creating shareable images. 


11.5 SCSI Port Features Under Application Control 
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The standard VMS SCSI port driver provides mechanisms by which the 
generic SCSI class driver can control the nature of data transfers and 
command transmission across the SCSI bus. An application uses the $QIO 
interface to tailor these mechanisms to the specific device it supports. 
Among the features under application program control are the following: 


e Data transfer mode 
¢ Disconnection and reselection 


¢ Command retry 
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¢ Command timeouts 


The following sections discuss these features. 


11.5.1 Setting the Data Transfer Mode 


The SCSI bus defines two data transfer modes, asynchronous and 
synchronous. In asynchronous mode, for each REQ from a target there is 
an ACK from the host prior to the next REQ from the target. Synchronous 
mode allows higher data transfer rates by allowing a pipelined data 
transfer mechanism where, for short bursts (defined by the REQ-ACK 
offset), the target can pipeline data to an initiator without waiting for the 
initiator to respond. 


Whether or not a port or a target device allows synchronous data 
transfers, it is harmless for the program to set up the connection to 

use such transfers. If synchronous mode is not supported, the port driver 
automatically uses asynchronous mode. 


To use synchronous mode in a transfer, a programmer using the generic 
SCSI class driver must ensure that both the SCSI port and the SCSI 
device involved in the transfer support synchronous mode. The SCSI 
port of the VAXstation 3520/3540 system allows both synchronous and 
asynchronous transfers, whereas that of MicroVAX/VAXstation 3100 
systems supports only asynchronous transfers. 


To set up a connection to use synchronous data transfer mode, a program 
using the generic SCSI class driver sets the syn bit in the flags field of 
the generic SCSI descriptor, the address of which is passed to the driver in 
the p1 argument to the $QIO request. 


11.5.2 Enabling Disconnection and Reselection 


The ANSI SCSI specification defines a disconnection facility that allows 

a target device to yield ownership of the SCSI bus while seeking or 
performing other time-consuming operations. When a target disconnects 
from the SCSI bus, it sends a sequence of messages to the initiator that 
cause it to save the state of the J/O transfer in progress. Once this is done, 
the target releases the SCSI bus. When the target is ready to complete 
the operation, it reselects the initiator and sends to it another sequence 
of messages. This sequence uniquely identifies the target and allows the 
initiator to restore the context of the suspended I/O operation. 


Whether disconnection should be enabled or disabled on a given connection 
depends on the nature and capabilities of the device involved in the 
transfer, as well as on the configuration of the system. In configurations 
where there is a slow device present on the SCSI bus, enabling 
disconnection on connections that transfer data to the device can increase 
bus throughput. By contrast, systems where most of the I/O activity 

is directed towards a single device for long intervals can benefit from 
disabling disconnection. By disabling disconnection when there is no 
contention on the SCSI bus, port drivers can increase throughput and 
decrease the processor overhead for each I/O request. 
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By default, the VMS class/port interface disables the disconnect facility on 
a connection. To enable disconnection, an application program using the 
generic SCSI class driver sets the dis bit of the flags field of the generic 
SCSI descriptor, the address of which is passed to the driver in the pl 
argument to the $QIO call. 


11.5.3 Disabling Command Retry 


The SCSI port driver implements a command retry mechanism, which is 
enabled on a given connection by default. 


When the command retry mechanism is enabled, the port driver retries 
up to three times any I/O operation that fails during the COMMAND, 
Message, Data, or STATUS phases. For instance, if the port driver detects 
a parity error during the Data phase, it aborts the I/O operation, logs 

an error, and retries the I/O operation. It repeats this sequence twice 
more, if necessary. If the I/O operation completes successfully during a 
retry attempt, the port driver returns success status to the class driver. 
However, if all retry attempts fail, the port driver returns failure status to 
the class driver. 


An application may need to disable the command retry mechanism under 
certain circumstances. For example, repeated execution of a command on 
a sequential device may produce different results than are intended by a 
single command request. A tape drive could perform a partial write and 

then repeat the write without resetting the tape position. 


An application program using the generic SCSI class driver can disable 
the command retry mechanism by setting the dpr bit of the flags field of 
the generic SCSI descriptor, the address of which is passed to the driver in 
the pl argument to the $QIO request. 


11.5.4 Setting Command Timeouts 
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The SCSI port driver implements several timeout mechanisms, some 
governed by the ANSI SCSI specification and others required by the VMS 
operating system. The timeouts required by the VMS operating system 
include the following: 


Timeout Description 


Phase change timeout | Maximum number of seconds for a target to change the 
SCSI bus phase or complete a data transfer. (This value is 
also known as the DMA timeout.) 


Upon sending the last command byte, the port driver waits 
this many seconds for the target to change the bus phase 
lines and assert REQ (indicating a new phase). Or, if the 
target enters the DATA IN or DATA OUT phase, the transfer 
must be completed within this interval. 
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Timeout Description 


Disconnect timeout Maximum number of seconds, from the time the initiator 
receives the DISCONNECT message, for a target to 
reselect the initiator so that it can proceed with the 
disconnected I/O transfer. 


An application program using the generic SCSI class driver is responsible 
for maintaining both of these timeout values. It has the following options: 


e Accepting a connection’s default value. The default value for both 
timeouts is 20 seconds. 


e Altering the connection’s default value. To modify the default values, 
the class driver specifies nonzero values for the phase change 
timeout and disconnect timeout fields of the generic SCSI 
descriptor, the address of which is passed to the driver in the pl 
argument to the $QIO system service call. 


11.6 Configuring a Device Using the Generic Class Driver 


The System Generation Utility (SYSGEN) loads the generic SCSI class 
driver into system virtual memory, creates additional data structures for 
the device unit, and calls the driver’s controller initialization routine 
and unit initialization routine. SYSGEN automatically loads and 
autoconfigures the SCSI port driver at system initialization. As part of 
autoconfiguration, SYSGEN polls each device on each SCSI bus. If the 
device identifies itself as a direct-access device, direct-access CDROM 
device, or flexible disk device, SYSGEN automatically loads the VMS disk 
class driver (DKDRIVER); if the device identifies itself as a sequential- 
access device, SYSGEN automatically loads the VMS tape class driver 
(MKDRIVER). If the autoconfiguration facility does not recognize the type 
of the SCSI device, it loads no driver. 


Consequently, if a non-Digital-supplied SCSI device requires that the 
generic class driver be loaded, it must be configured by an explicit 
SYSGEN CONNECT command, as follows: 


$ RUN SYSSSYSTEM: SYSGEN 
SYSGEN> CONNECT GKpd0Ou /NOADAPTER 


In this command, GK is the device mnemonic for the generic SCSI class 
driver (GKDRIVER); p represents the SCSI port ID (for instance, the 
controller ID A or B); d represents the SCSI device ID (a digit from 0 to 7); 
0 signifies the digit zero; and uw represents the SCSI logical unit number (a 
digit from 0 to 7). 


Multiple devices residing on any SCSI bus in the system can share 
GKDRIVER as a class driver, as long as a SYSGEN CONNECT command 
is issued for each target device that requires the driver. 


Because just one connection can exist through the SCSI port driver to each 
target, the generic class driver cannot be used for a target if a different 
SCSI class driver is already connected to that target. For example, if the 
SCSI disk class driver has a connection to device ID 2 on the SCSI bus 
identified by SCSI port ID B (DKB200), the generic class driver cannot be 
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used to communicate with this disk. An attempt to connect GADRIVER 
for this target results in GKB200 being placed off line. 


11.6.1 Disabling the Autoconfiguration of a SCSI Device 


Note that, in special cases, you may need to prevent SYSGEN’s 
autoconfiguration facility from loading the VMS disk or tape class driver 
for a device with a specific port ID and device ID. This would be the case 
if a non-Digital-supplied SCSI device should identify itself as either a 
random-access or sequential-access device and were to be controlled by the 
generic SCSI class driver. 


To disable the loading of a VMS disk or tape driver for any given device ID, 
VMS Version 5.4 defines the special SYSGEN parameter SCSI_NOAUTO. 


The SCSI_NOAUTO system parameter, as shown in Figure 11-8, stores 
a bit mask of 32 bits in which the low-order byte corresponds to the first 
SCSI bus (PKAO), the second byte corresponds to the second SCSI bus 
(PKBO), and so on. For each SCSI bus, setting the low-order bit inhibits 
automatic configuration of the device with SCSI device ID 0; setting the 
second low-order bit inhibits automatic configuration of the device with 
SCSI device ID 1, and so forth. For instance, the value 000020001, would 
prevent the device with SCSI ID 5 on the bus identified by SCSI port ID B 
from being configured. By default, all of the bits in the mask are cleared, 
allowing all devices to be configured. 


Figure 11-3 SCSI_NOAUTO System Parameter 


7 07 07 07 0 + SCSI Device ID 


D C B A + SCSI Port ID 
ZK-1371A-GE 


11.7. Assigning a Channel to GKDRIVER 
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An application program assigns a channel to the generic SCSI class driver 
using the standard call to the $ASSIGN system service, as described in the 
VMS System Services Reference Manual. The application program specifies 
a device name and a word to receive the channel number. 
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11.8 Issuing a $QIO Request to the Generic Class Driver 


The format of the Queue I/O Request ($QIO) system service that initiates 
a request to the SCSI generic class driver is as follows. This explanation 
concentrates on the special elements of a $QIO request to the SCSI generic 
class driver. For a detailed description of the $QIO system service, see the 
VMS System Services Reference Manual. 


VAX MACRO Format 


$QIO_ [efn] ,chan ,func ,iosb ,[astadr] ,[astprm] - 
»P1 ,p2 [,p3] [,P4] [5] [,p6] 


High-Level Language Format 


SYS$QIO ([efn] ,chan ,func ,iosb ,[astadr] ,[astprm] 
»P1 ,p2 [,p3] [,p4] [,p5] Lpé]) 


Arguments 


chan 


I/O channel assigned to the device to which the request is directed. The 
chan argument is a word value containing the number of the channel, as 
returned by the Assign I/O Channel ($ASSIGN) system service. 


func 


Longword value containing the IO$_ DIAGNOSE function code. Only the 
I0$_DIAGNOSE function code is implemented in the generic SCSI class 
driver. 


iosb 
I/O status block. The iosb argument is required in a request to the generic 
SCSI class driver; it has the following format: 


31 1615 0 
a = 

31 24 23 1615 0 
jscsists| | Tamer | 0562 
ZK-1372A-GE 


The VMS status code provides the final status indicating the success or 
failure of the SCSI command. The SCSI status byte contains the status 
value returned from the target device, as defined in the ANSI SCSI 
specification. The transfer count field specifies the actual number of bytes 
transferred during the SCSI bus DATA IN or DATA OUT phase. 


11-11 


Using the VMS Generic SCSI Class Driver 
11.8 Issuing a $QIO Request to the Generic Class Driver 


11-12 


[efn] 

{astadr] 

[astprm] 

These arguments apply to $QIO system service completion. For an 
explanation of these arguments, see the VMS System Services Reference 
Manual. 


p1 
Address of a generic SCSI descriptor of the following format: 


31 0 
opcode 
flags 

SCSI command address 
SCSI command length 

SCSI data address 

SCSI data length 

SCSI pad length 


phase change timeout 


disconnect timeout 


reserved 





ZK-1373A-GE 


p2 
Length of the generic SCSI descriptor. 
Descriptor Fields 


opcode 


Currently, the only supported opcode is 1, indicating a pass-through 
function. Other opcode values are reserved for future expansion. 


flags 
Bit map having the following format: 


31 4 


3 2 1 0 
[ae delle] 
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Bits in the flags bit map are defined as follows: 


Field Definition 


dir Direction of transfer. 


If this bit is set, the target is expected at some time to enter the DATA IN phase 
to send data to the host. To facilitate this, the port driver maps the specified 
data buffer for write access. 


If this bit is clear, the target is expected at some time to enter the DATA OUT 
phase to receive data from the host. To facilitate this, the port driver maps the 
specified data buffer for read access. 


The generic SCSI class driver ignores the dir flag if either the SCSI data 
address or SCSI data length field of the generic SCSI descriptor is zero. 


dis Enable disconnection. 


If this bit is set, the target device is allowed to disconnect during the execution 
of the command. 


If this bit is clear, the target cannot disconnect during the execution of the 
command. 


Note that targets that hold on to the bus for long periods of time without 
disconnecting can adversely affect system performance. See Section 11.5.2 for 
additional information. 


syn Enable synchronous mode. 


If this bit is set, the port driver uses synchronous mode for data transfers, if 
both the host and target allow this mode of operation. 


If this bit is clear, or synchronous mode is not supported by either the host or 
target, the port driver uses asynchronous mode for data transfers. 


See Section 11.5.1 for additional information. 
dpr _ Disable port retry. 


If this bit is clear, the port driver retries, up to three times, any command that 
fails with a timeout, bus parity, or invalid phase transition error. 


If this bit is set, the port driver does not retry commands for which it detects 
failure. 


See Section 11.5.3 for additional information. 


SCSI command address 
Address of a buffer containing a SCSI command. 


SCSI command length 
Length of the SCSI command. The maximum length of the SCSI command 
is 128 bytes. 


SCSI data address 
Address of a data buffer associated with the SCSI command. 


If the dir bit is set in the flags field, data is written into this buffer during 
the execution of the command. Otherwise, data is read from this buffer 
and sent to the target device. 


If the SCSI command requires no data to be transferred, then the SCSI 
data address field should be clear. 
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SCSI data length 

Length in bytes of the data buffer pointed to by the SCSI data address 
field. For the MicroVAX/VAXstation 3100 and VAXstation 3520/3540 
systems, the maximum data buffer size is 65,535 bytes. 


If the SCSI command requires no data to be transferred, then this field 
should be clear. 


SCSI pad length 

This field is used to accommodate SCSI device classes that require that the 
transfer length be specified in terms of a larger data unit than the count 
of bytes expressed in the SCSI data length field. If the total amount of 
data requested in the SCSI command does not match that specified in the 
SCSI data length field, this field must account for the difference. 


For example, suppose an application program is using the generic class 
driver to read the first 2 bytes of a disk block. The length field in the SCSI 
READ command contains 1 (indicating one logical block, or 512 bytes), 
while the SCSI data length field contains a 2. The SCSI pad length 
field must contain the difference, 510 bytes. 


For most transfers, this field should contain 0. Failure to initialize the 
SCSI pad length field properly causes port driver timeouts and SCSI bus 
resets. 


phase change timeout 


Maximum number of seconds for a target to change the SCSI bus phase 
or complete a data transfer. A value of 0 causes the SCSI port driver’s 
default phase change timeout value of 4 seconds to be used. 


See Section 11.5.4 for additional information. 


disconnect timeout 


Maximum number of seconds for a target to reselect the initiator to 
proceed with a disconnected I/O transfer. A value of 0 causes the SCSI 
port driver’s default disconnect timeout value of 4 seconds to be used. 


See Section 11.5.4 for additional information. 


11.9 Generic SCSI Class Driver Device Information 
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A call to the Get Device/Volume Information (S$GETDVI) system service 
returns the following information for any device serviced by the generic 
SCSI class driver. (See the description of the $GETDVI system service in 
the VMS System Services Reference Manual.) 


$GETDVI returns the following device characteristics when you specify 
the item code DVI$_DEVCHAR: 


DEV$M_AVL Available device 
DEV$M_IDV Input device 
DEV$M_ODV Output device 
DEV$M_SHR Shareable device 
DEV$M_RND Random-access device 


DVI$DEVCLASS returns the device class, which is DC$_MISC; 
DVI$DEVTYPE returns the device type, which is DT$_GENERIC_SCSI. 
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Generic SCSI Class Driver Programming Example 


The following application program uses the generic SCSI class driver to 
send a SCSI INQUIRY command to a device. 


/* 
GKTEST.C 


This program uses the SCSI generic class driver to send an inquiry command 
to a device on the SCSI bus. 


xf 
#include ctype 
/* Define the descriptor used to pass the SCSI information to GKDRIVER */ 


#define OPCODE 0 

#define FLAGS 1 

#define COMMAND ADDRESS 2 
#define COMMAND LENGTH 3 
#define DATA ADDRESS 4 
#define DATA_LENGTH 5 
#define PAD LENGTH 6 

#define PHASE TIMEOUT 7 
#define DISCONNECT TIMEOUT 8 


#define FLAGS READ 1 
#define FLAGS DISCONNECT 2 


#define GK_EFN 1 
#define SCSI_STATUS MASK 0X3E 


#define INQUIRY _OPCODE 0x12 
#define INQUIRY_DATA_ LENGTH 0x30 


globalvalue 
IO$_DIAGNOSE; 


short 
gk_chan, 
transfer length; 
int 
i, 
status, 
gk_device_desc[2], 
gk_iosb[2], 
gk_desc[15]; 


char 
scsi_status, 
inquiry command[6] = {INQUIRY_OPCODE, 0, 0, 0, INQUIRY_DATA_LENGTH, 0}, 
inquiry data[INQUIRY DATA LENGTH], 
gk_device[] = {"GKAO"}; 


main () 


{ 
/* Assign a channel to GKAO */ 


gk_device desc[0] = 4; 

gk_device_desc[1] = &gk_device[0]; 

status = sysSassign (&gk_device desc[0], &gk_chan, 0, 0); 
if (!(status & 1)) sysSexit (status); 


/* Set up the descriptor with the SCSI information to be sent to the target */ 
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gk_desc[OPCODE] = 1; 
gk_desc[FLAGS] = FLAGS READ + FLAGS DISCONNECT; 


gk_desc[COMMAND ADDRESS] = &inquiry command[0]; 
gk_desc[COMMAND LENGTH] = 6; 
gk_desc[DATA_ ADDRESS] = &inquiry data[0]; 


gk_desc[DATA_ LENGTH] = INQUIRY_DATA_ LENGTH; 

gk_desc[PAD LENGTH] = 0; 

gk_desc[PHASE TIMEOUT] = 0; 

gk_desc [DISCONNECT TIMEOUT] = 0; 

for (i=9; i<15; i++) gk_desc[i] = 0; /* Clear reserved fields */ 


/* Issue the QIO to send the inquiry command and receive the inquiry data */ 


status = sys$qiow (GK_EFN, gk_chan, IO$ DIAGNOSE, gk_iosb, 0, 0, 
&gk_desc[0], 15*4, 0, 0, 0, 0); 


/* Check the various returned status values */ 


if (! (status & 1)) sys$Sexit (status); 
if (!(gk_iosb[0] & 1)) sysSexit (gk_iosb[0] & Oxffff); 
scsi_status = (gk_iosb[1] >> 24) & SCSI_STATUS_MASK; 


if (scsi_status) { 
printf ("Bad SCSI status returned: %02.2x\n", scsi_status); 
sysSexit (1); 

} 


/* The command succeeded. Display the SCSI data returned from the target */ 


transfer length = gk_iosb[0] >> 16; 
printf ("SCSI inquiry data returned: "); 
for (i=0; i<transfer_ length; i++) { 
if (isprint (inquiry data[i])) 
printf ("Sc", inquiry data[i]); 
else 
printf ("."); 
} 
Printe® <*\n")s 
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A 


A.1 


I/O Function Codes 


This appendix lists the function codes and function modifiers defined in 
the $IODEF macro. The arguments for these functions are also listed. 


ACP-QIO Interface Driver 


Functions 


lO$_CREATE 
lO$_ACCESS 
lO$_DEACCESS 
l\O$_MODIFY 
\O$_DELETE 
lO$_ACPCONTROL 


lO$_MOUNT 


Arguments 


P1 - FIB descriptor 
address 

P2 - file name string 
address 

P3 - result string length 
address 

P4 - result string 
descriptor address 

P5 - attribute list 
address 


(none) 


1Only for 1O$_CREATE and lO$_ACCESS 
2Only for 1O$_CREATE and l|O$ DELETE 
3Only for |O$ ACPCONTROL 


QIO Status Returns 


SS$_ACCONFLICT 
SS$_BADCHKSUM 
SS$_BADFILEVER 
SS$_BADQFILE 
SS$_DEVICEFULL 
SS$_DUPDSKQUOTA 
SS$_EXBYTLM 
SS$_FCPREWNDERR 
SS$_FILELOCKED 
SS$_FILESEQCHK 
SS$_HEADERFULL 
SS$_ILLCNTRFUNC 
SS$_NOPRIV 


SS$_ACPVAFUL 
SS$_BADFILEHDR 
SS$_BADIRECTORY 
SS$_BLOCKCNTERR 
SS$_DIRFULL 
SS$_DUPFILENAME 
SS$_EXDISKQUOTA 
SS$_FCPSPACERR 
SS$_FILENUMCHK 
SS$_FILESTRUCT 
SS$_IBCERROR' 
SS$_NODISKQUOTA 
SS$_NOQFILE 


Modifiers 


\O$M_CREATE' 
lO$M_ACCESS" 
lO$M_DELETE? 
lO$M_DMOUNT? 


(none) 


SS$_BADATTRIB 
SS$_BADFILENAME 
SS$_BADPARAM 
SS$_CREATED 
SS$_DIRNOTEMPTY 
SS$_ENDOFFILE 
SS$_FCPREADERR 
SS$_FCPWRITERR 
SS$_FILEPURGED 
SS$_FILNOTEXP 
SS$_IDXFILEFULL 
SS$_NOMOREFILES 
SS$_NOSUCHFILE 


'The second longword of the IOSB contains a job controller status code. 
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QIO Status Returns 


SS$_NOTAPEOP SS$_NOTLABELMT SS$_NOTPRINTED' 
SS$_NOTVOLSET SS$_OVRDSKQUOTA SS$_QFACTIVE 
SS$_QFNOTACT SS$_SERIOUSEXCP SS$_SUPERSEDE 


SS$_TAPEPOSLOST SS$_TOOMANYVER SS$_WRITLCK 
SS$_WRONGACP 


'The second longword of the |OSB contains a job controller status code. 





A.2 Card Reader Driver 


Functions Arguments Modifiers 
lO$_READLBLK P1 - buffer address lO$M_BINARY 
lO$_READVBLK P2 - byte count lO$M_PACKED 
lO$_READPBLK 

lO$_SETMODE P1 - characteristics (none) 
1O$_SETCHAR buffer address 

lO$_SENSEMODE (none) (none) 


QIO Status Returns 


SS$_ABORT SS$_DATAOVERUN SS$_ENDOFFILE SS$_NORMAL 





A.3 Disk Drivers 


Functions Arguments Modifiers 
lIO$_READVBLK P1 - buffer address IO$M_INHSEEK' 
lO$_READLBLK P2 - byte count lIO$M_DATACHECK? 
lO$_READPBLK* P3 - disk address |O$M_DELDATA® 
lO$_WRITEVBLK IO$M_INHRETRY 
lO$_WRITELBLK IO$M_ERASE® 
1O$_WRITEPBLK4 

lO$_WRITECHECK? P1 - buffer address (none) 


P2 - byte count 
P3 - disk address 


1Only for IOSREADPBLK and 10$_WRITEPBLK (not for TU58, RX01, RX02, RBO2, or RLO2) 
2Not for RX01 and RX02 

3Only for 1O$_WRITEPBLK on RX02 
4Not for DSA disks 

5Only for write functions 
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Functions 


lO$_SENSECHAR 
l\O$_SENSEMODE 
l1O$_PACKACK 
lO$_AVAILABLE 
lO$_UNLOAD 


1O$_SEARCH 


lO$_SEEK‘* 


l\O$_FORMAT 


lIO$_CREATE 
lO$_ACCESS 
l\O$_DEACCESS 
lO$_MODIFY 
lO$_DELETE 
lIO$_ACPCONTROL 


4Not for DSA disks 


Arguments 


(none) 


P1 - read/write 
head position 


P1 - seek to 
specified 
cylinder 


P1 - RX02 density 


P1 - FIB descriptor 
address 

P2 - file name string 
address 

P3 - result string 
length address 

P4 - result string 
descriptor 
address 

P5 - attribute list 
address 


SOnly for 1O$ CREATE and |O$_ ACCESS 
7Only for 1O$_ CREATE and !0$_DELETE 
8Only for |O$ ACPCONTROL 


QIO Status Returns 


SS$_ABORT 
SS$_DATACHECK 
SS$_FORCEDERR 
SS$_IVADDR 
SS$_NONEXDRV 
SS$_PARITY 
SS$_TIMEOUT 
SS$_WASECC 


SS$_CANCEL 
SS$_DATAOVERUN 
SS$_FORMAT 
SS$_IVBUFLEN 
SS$_NORMAL 
SS$_RCT 
SS$_UNSAFE 
SS$_WRITLCK 
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Modifiers 


(none) 


(none) 


(none) 


(none) 


lO$M_CREATE® 
lO$M_ACCESS® 
|O$M_DELETE’ 
lO$M_DMOUNT® 


SS$_CTRLERR 
SS$_DRVERR 
SS$_ILLIOFUNC 
SS$_MEDOFL 
SS$_OPINCOMPL 
SS$_RDDELDATA 
SS$_VOLINV 
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A.4 Laboratory Peripheral Accelerator Driver 
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Functions 


lO$_LOADMCODE 


lO$_STARTMPROC 
lO$_INITIALIZE 


lO$_SETCLOCK 


lO$_STARTDATA 


High-Level Language 
Subroutines 
LPASADSWP 
LPASDASWP 
LPA$SDISWP 
LPASDOSWP 
LPA$SLAMSKS 
LPASSETADC 
LPA$SETIBF 
LPA$STPSWP 
LPA$CLOCKA 
LPA$CLOCKB 
LPA$XRATE 
LPASIBFSTS 
LPA$IGTBUF 


Arguments 


P1 - starting address of 
microcode to be loaded 

P2 - load byte count 

P83 - starting microprogram 
address to receive 
microcode 


(none) 


P1 - address of initialize 
command table 

P2 - initialize command 
buffer length 


P2 - mode of operation 

P3 - clock control and 
status 

P4 - real-time clock preset 
value (two’s complement) 


P1 - data transfer command 
table address 

P2 - data transfer command 
table length 

P3 - normal completion AST 
address 

P4 - overrun completion AST 
address 


Functions 


Start A/D converter sweep. 
Start D/A converter sweep. 
Start digital input sweep. 
Start digital output sweep. 


Modifiers 


(none) 


(none) 
(none) 


(none) 


lO$_SETEVF 


Specify LPA11-K controller and digital mask words. 


Specify channel select parameters. 


Specify buffer parameters. 
Stop sweep. 

Set Clock A rate. 

Set Clock B rate. 


Compute clock rate and preset value. 


Return buffer status. 


Return next available buffer. 


I/O Function Codes 
A.4 Laboratory Peripheral Accelerator Driver 


High-Level Language 





Subroutines Functions 

LPASINXTBF Alter buffer order. 

LPASIWTBUF Return next buffer or wait. 

LPA$RLSBUF Release buffer to LPA11-K. 
LPASRMVBUF Remove buffer from device queue. 
LPASCVADF Convert A/D input to floating point. 
LPA$FLT16 Convert unsigned integer to floating point. 
LPA$LOADMC Load microcode and initialize LPA11-K. 


QIO Status Returns 





SS$_ABORT SS$_BADPARAM SS$_BUFNOTALIGN 
SS$_CANCEL SS$_CTRLERR SS$_DATACHECK 
SS$_DEVACTIVE SS$_DEVCMDERR SS$_DEVREQERR 
SS$_EXQUOTA SS$_INSFBUFDP SS$_INSFMAPREQ 
SS$_INSFMEM SS$_IVBUFLEN SS$_IVMODE 
SS$_MCNOTVALID SS$_PARITY SS$_POWERFAIL 
SS$_TIMEOUT 

A.5 Line Printer Driver 
Functions Arguments Modifiers 
1IO$_WRITEVBLK P1 - buffer address (none) 


1IO$_WRITELBLK P2 - buffer size 
1O$_WRITEPBLK P3 - (ignored) 
P4 - carriage control 


specifier’ 
lO$_ SENSEMODE (none) (none) 
1O$_SETMODE P1 - characteristics (none) 
1IO$_SETCHAR buffer address 


'Only for 1O$_WRITEVBLK and 10$_WRITELBLK 


QIO Status Returns 


SS$_ABORT  SS$_ACCVIO SS$_CANCEL SS$ NORMAL 


A.6 


I/O Function Codes 
A.6 Magnetic Tape Drivers 





Magnetic Tape Drivers 


Functions 


lO$_READVBLK 
lO$_READLBLK 
lO$_READPBLK 


lO$_WRITEVBLK 
lO$_WRITELBLK 
lO$_WRITEPBLK 


1\O$_SETMODE 
lO$_SETCHAR 


lO$_CREATE 
lO$_ACCESS 
lO$_DEACCESS 
lO$_MODIFY 
lO$_ACPCONTROL 


lO$_SKIPFILE 
lO$_SKIPRECORD 


lO$_REWIND 
lO$_REWINDOFF 
lO$_UNLOAD 


lO$_WRITEOF 


lO$_SENSEMODE 
lO$_SENSECHAR 


'Not for TS04 and TU80 


Arguments 


P1 - buffer address 
P2 - byte count 


Pi - buffer address 
P2 - byte count 


P1 - characteristics buffer 


address 


P2 - characteristics buffer 


length? 


P1 - FIB descriptor 
address 

P2 - file name string 
address 

P3 - result string length 
address 

P4 - result string 
descriptor address 


P5 - attribute list address 


P1 - skip n tape marks 
P1 - skip n blocks 


(none) 


(none) 


P1 - characteristics 
buffer address® 

P2 - characteristics 
buffer length® 


2Only for TE16, TU45, and TU77 


3Not for TK50 


4Only for |O$_CREATE and lO$_ACCESS 
5Only for |O$_ACPCONTROL 
7IO$M_ERASE takes no arguments; only for 1O$_WRITELBLK and 10$_WRITEPBLK on 


TMSCP drives. 


8Only for TU81-Plus drives 
8Only for TMSCP drives 


Modifiers 


|O$M_DATACHECK" 
IO$M_INHRETRY 
|O$M_REVERSE® 


\O$M_DATACHECK" 
lO$M_INHRETRY 
IO$M_INHEXTGAP? 
1O$M_NOWAIT® 
lO$M_ERASE’ 


|O$M_CREATE* 
lO$M_ACCESS4 
|O$M_DMOUNT?® 


lO$M_INHRETRY 
lO$M_NOWAIT® 


[O$M_INHRETRY 
lO$M_NOWAIT® 


IO$M_INHRETRY 
IO$M_NOWAIT 


IO$M_INHEXTGAP? 
1O$M_INHRETRY 
|O$M_NOWAIT® 


lIO$M_INHRETRY 


Functions Arguments 
lO$_DSE® (none) 
1O0$_PACKACK 


1O$_AVAILABLE 


SOnly for TU78, TU81, TA81, and TA78 


QIO Status Returns 


I/O Function Codes 
A.6 Magnetic Tape Drivers 


Modifiers 


(none) 





SS$_ABORT SS$_CANCEL SS$_CTRLERR 
SS$_DATACHECK SS$_DATAOVERUN SS$_DEVOFFLINE 
SS$_DRVERR SS$_ENDOFFILE SS$_ENDOFTAPE 
SS$_ENDOFVOLUME SS$_FORMAT SS$_ILLIOFUNC 
SS$_MEDOFL SS$_NONEXDRV SS$_NORMAL 
SS$_OPINCOMPL SS$_PARITY SS$_SERIOUSEXCP 
SS$_TIMEOUT SS$_UNSAFE SS$_VOLINV 
SS$_WRITLCK 
Mailbox Driver 
Functions Arguments Modifiers 
l1O$_READVBLK P1 - buffer lOSM_NOW 
10$_READLBLK address lO$M_ 
1O$_READPBLK P2 - buffer size NORSWAIT' 
1O$_WRITEVBLK 
1O$_WRITELBLK 
l1O$_WRITEPBLK 
1O$_WRITEOF (none) lOSM_NOW 
10$_ SETMODE!IO$M_READATTN P1 - AST address (none) 
1O$_SETMODE!NO$M_WRTATTN P2 - AST parameter 
P3 - access mode 
lO$_SETMODE!IO$M_SETPROT P2 - volume (none) 
protection 
mask 
1Only for write functions 
QIO Status Returns 
SS$_ABORT SS$_BUFFEROVF SS$_ENDOFFILE SS$_NORMAL 
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A.8 


Terminal Driver 


/O Function Codes 
A.8 Terminal Driver 


Functions 


lO$_READVBLK 
lO$_READLBLK 
1O$_READPROMPT 


1O$_READVBLK 


lO$_WRITEVBLK 
1O$_WRITELBLK 
1O$_WRITEPBLK 


lIO$_SETMODE 
lO$_SETCHAR 


1O$_SETMODE 
1O$_SETCHAR 


1IO$_SETMODE 


1O$_SETMODE 
lO$_SETCHAR 


Arguments 


P1 - buffer address 

P2 - buffer size 

P38 - timeout 

P4 - read terminator 
block address 

P5 - prompt string 
buffer address 

P6 - prompt string 
buffer size’ 


P1 - buffer address 

P2 - buffer size 

P3 - access mode to 
probe itemlist 

P4 - (zero) 

P5 - itemlist buffer 
address 

P6 - itemlist buffer 
size 

P1 - buffer address 

P2 - buffer size 

P3 - (ignored) 

P4 - carriage control 
specifier® 


P1 - characteristics 
buffer address 

P2 - characteristics 
buffer size 

P3 - speed specifier 

P4 - fill specifier 

P5 - parity flags 


(none) 


P1 - buffer address 
P2 - buffer size 


P1 - AST service 
routine address 

P2 - AST parameter 

P3 - access mode to 
deliver AST 


1Only for 1O$_READPROMPT 
2Only for itemlist read function. Do not specify with other modifiers. 
3Only for 1O$_WRITELBLK and |O$_WRITEVBLK 





Modifiers 


lO$M_NOECHO 
lO$M_CVTLOW 
lIO$M_NOFILTR 
lO$M_TIMED 
lO$M_PURGE 
lO$M_DSABLMBX 
lIO$M_TRMNOECHO 
lO$M_ESCAPE 


lO$M_EXTEND? 


lO$M_CANCTRLO 
lIOSM_ENABLMBX 
lO$M_NOFORMAT 
lIO$M_REFRESH 
lIO$M_BREAKTHRU 


lO$M_HANGUP 
lO$M_BRDCST 


lO$M_CTRLCAST 
lO$M_CTRLYAST 


I/O Function Codes 


A.8 Terminal Driver 


Functions Arguments Modifiers 
lO$_SETMODE P1 - AST service IO$M_OUTBAND 
lO$_SETCHAR routine address lO$M_TT_ABORT* 
P2 - character mask IO$M_INCLUDE* 
address 
P3 - access mode to 
deliver AST 
lO$_SETMODE P1 - address of lO$M_SET_MODEM® 
lO$_SETCHAR control signals lIOSM_MAINT 
lO$_SETMODE (none) 1\O$M_LOOP® 
lO$_SETCHAR 1O$M_UNLOOP® 
lOSM_MAINT 
lO$_TTY_PORT lIO$M_LT_CONNECT 
IO$M_LT_DISCON 
lO$_TTY_PORT P1 - item list® IO$M_LT_MAP_PORT 
address 
P2 - queued status 
1O$_TTY_PORT P1 - service name IO$M_LT_RATING 
descriptor 
address 


P2 - service rating 


lIO$_SENSEMODE 
10$_SENSECHAR 


P1 - characteristics 
buffer address 

P2 - characteristics 
buffer size 


IO$M_TYPEAHDCNT 


lIO$_SENSEMODE 
l\O$_SENSECHAR 


P1 - address of input 
modem signal 
block 


P1 - buffer address 
P2 - buffer size 


lO$M_RD_MODEM 


lO$_SENSEMODE lIO$M_BRDCST 


4Only with IO$M_OUTBAND 
5Only with IO$M_MAINT 


Sitem list: 1O$V_LT_MAP_NODNAM, |O$V_LT_MAP_PORNAM, IO$V_LT_MAP_SRVNAM, 
lO$V_LT_MAP_LNKNAM, and lO$V_LT_MAP_NETADR. 


QIO Status Returns 


SS$_ABORT SS$_BADESCAPE SS$_BADPARAM 
SS$_CANCEL $S$_CONTROLC SS$_CONTROLO 
SS$_CONTROLY SS$_DATAOVERUN SS$_INCOMPAT 
SS$_NORMAL SS$_PARITY SS$_PARTESCAPE 
SS$_TIMEOUT 
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Tables 


Table B—1 lists the DEC Multinational Character Set. The DEC 
Multinational Character set is an eight-bit character set with 256 
characters. The first 128 characters in the set correspond to the ASCII 
character set. The VAX EDT Reference Manual lists the graphics for 
these characters and describes how to enter them from various types of 


terminals. 


Table B—1 DEC Multinational Character Set 


Octal 
Hex Code Code 


00 000 
01 001 
02 002 
03 003 
04 004 
05 005 
06 006 
07 007 
08 010 
09 011 
0A 012 
OB 013 
0c 014 
0D 015 
OE 016 
OF 017 
10 020 
11 021 
12 022 
13 023 
14 024 
15 025 


Decimal 
Code 


Char or 
Abbrev. 


Description 


ASCII Control Characters’ 


000 
001 
002 
003 
004 
005 
006 
007 
008 
009 
010 
011 

012 
013 
014 
015 
016 
017 
018 
019 
020 
021 


NUL 
SOH 
STX 
ETX 
EOT 
ENQ 
ACK 
BEL 
BS 
HT 
LF 
VT 
FF 
CR 
SO 
S| 
DLE 
DCt 
DC2 
DC3 
DC4 
NAK 


null character 

start of heading (CTRL/A) 
start of text (CTRL/B) 

end of text (CTRL/C) 

end of transmission (CTRL/D) 
enquiry (CTRL/E) 
acknowledge (CTRL/F) 

bell (CTRL/G) 

backspace (CTRL/H) 
horizontal tabulation (CTRL/I) 
line feed (CTRL/J) 

vertical tabulation (CTRL/K) 
form feed (CTRL/L) 

carriage return (CTRL/M) 
shift out (CTRL/N) 

shift in (CTRL/O) 

data link escape (CTRL/P) 
device control 1 (CTRL/Q) 
device control 2 (CTRL/R) 
device control 3 (CTRL/S) 
device control 4 (CTRL/T) 
negative acknowlege (CTRL/U) 


'The ALTMODE and DELETE characters (decimal 125, 126, and 127) are also control 


characters. 


(continued on next page) 
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Tables 


B-2 


Table B—1 (Cont.) 


Hex Code 


16 
17 


18 
19 
1A 
1B 
1c 
1D 
1E 
1F 


20 
21 

22 
23 
24 
25 
26 
27 
28 
29 
2A 
2B 
2C 
2D 
2E 
2F 
30 
31 

32 
33 


Octal 
Code 


026 
027 


030 
031 
032 
033 
034 
035 
036 
037 


040 
041 
042 
043 
044 
045 
046 
047 
050 
051 
052 
053 
054 
055 
056 
057 
060 
061 
062 
063 


DEC Multinational Character Set 


Decimal 
Code 


Char or 
Abbrev. 


Description 


ASCII Control! Characters' 


022 
023 


024 
025 
026 
027 
028 
029 
030 
031 


SYN 
ETB 


CAN 
EM 
SUB 
ESC 
FS 
GS 
RS 
US 


synchronous idle (CTRL/V) 


end of transmission block 
(CTRLW) 


cancel (CTRL/X) 

end of medium (CTRL/Y) 
substitute (CTRL/Z) 
escape 

file separator 

group separator 

record separator 

unit separator 


ASCIi Special and Numeric Characters 


032 
033 
034 
035 
036 
037 
038 
039 
040 
041 
042 
043 
044 
045 
046 
047 
048 
049 
050 
051 


~ 


~ — ~! 


ons oO ™~ * 


space 

exclamation point 
quotation marks (double quote) 
number sign 

dollar sign 

percent sign 

ampersand 

apostrophe (single quote) 
opening parenthesis 
closing parenthesis 
asterisk 

plus 

comma 

hyphen or minus 

period or decimal point 
slash 

zero 

one 

two 

three 


'The ALTMODE and DELETE characters (decimal 125, 126, and 127) are also control 


characters. 


(continued on next page) 
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Table B-1 (Cont.) DEC Multinational Character Set 


Octal Decimal Char or 
Hex Code Code Code Abbrev. Description 


ASCIl Special and Numeric Characters 


34 064 052 4 four 

35 065 053 5 five 

36 066 054 6 Six 

37 067 055 7 seven 

38 070 056 8 eight 

39 071 057 9 nine 

3A 072 058 : colon 

3B 073 059 : semicolon 
3C 074 060 < less than 
3D 075 061 m= equals 

3E 076 062 greater than 


“OV 


3F 077 063 question mark 


ASCIi Aipha Characters 





40 100 064 @ commercial at sign 
41 101 065 A uppercase A 
42 102 066 B uppercase B 
43 103 067 C uppercase C 
44 104 068 D uppercase D 
45 105 069 E uppercase E 
46 106 070 F uppercase F 
47 107 071 G uppercase G 
48 110 072 H uppercase H 
49 111 073 | uppercase | 
4A 112 074 J uppercase J 
4B 113 075 K uppercase K 
4c 114 076 L uppercase L 
4D 115 077 M uppercase M 
4E 116 078 N uppercase N 
4F 117 079 O uppercase O 
50 120 080 P uppercase P 
51 121 081 Q uppercase Q 
52 122 082 R uppercase R 
53 123 083 Ss uppercase S 


(continued on next page) 
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Tables 


Table B—1 (Cont.) DEC Multinational Character Set 


Octal Decimal Char or 
Hex Code Code Code Abbrev. Description 


ASCII Alpha Characters 





54 124 084 T uppercase T 
55 125 085 U uppercase U 
56 126 086 V uppercase V 
57 127 087 W uppercase W 
58 130 088 X uppercase X 
59 131 089 Y uppercase Y 
5A 132 090 Z uppercase Z 
5B 133 091 [ left bracket 
5C 134 092 \ backslash 
5D 135 093 ] right bracket 
5E 136 094 x circumflex 
5F 137 095 _ underscore 
60 140 096 ‘ grave accent 
61 141 097 a lowercase a 
62 142 098 b lower@ise b 
63 143 099 Cc lowercase c 
64 144 100 d lowercase d 
65 145 101 e lowercase e 
66 146 102 f lowercase f 
67 147 103 g lowercase g 
68 150 104 h lowercase h 
69 151 105 i lowercase i 
6A 152 106 j lowercase j 
6B 153 107 k lowercase k 
6C 154 108 lowercase | 
6D 155 109 m lowercase m 
6E 156 110 n lowercase n 
6F 157 111 Oo lowercase 0 
70 160 112 p lowercase p 
71 161 113 q lowercase q 
72 162 114 r lowercase r 
73 163 115 s lowercase s 
74 164 116 t lowercase t 
75 165 117 u lowercase u 


(continued on next page) 
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Tables 


Table B—1 (Cont.) DEC Multinational Character Set 


Hex Code 


76 
77 
78 
79 
7A 
7B 
7C 
7D 
7E 
7F 
80 
81 

82 
83 
84 
85 
86 
87 
88 
89 


8A 
8B 
8C 
8D 
8E 
8F 
90 
91 

92 
93 
94 
95 
96 
97 


Octal 
Code 


166 
167 
170 
171 
172 
173 
174 
175 
176 
177 
200 
201 
202 
203 
204 
205 
206 
207 
210 
211 


212 
213 
214 
215 
216 
217 
220 
221 
222 
223 
224 
225 
226 
227 


Decimal Char or 
Code Abbrev. Description 


ASCII Alpha Characters 


118 Vv lowercase v 

119 w lowercase w 

120 Xx lowercase x 

121 y lowercase y 

122 z lowercase Z 

123 { left brace 

124 | vertical line 

125 } right brace (ALTMODE) 

126 ~ tilde (ALTMODE) 

127 DEL rubout (DELETE) 

128 — [reserved] 

129 — [reserved] 

130 = [reserved] 

131 — [reserved] 

132 IND index 

133 NEL next line 

134 SSA start of selected area 

135 ESA end of started area 

136 HTS horizontal tab set 

137 HTJ horizontal tab set with 
justification 

138 VTS vertical tab set 

139 PLD partial line down 

140 PLU partial line up 

141 RI reverse index 

142 SS2 single shift 2 

143 S$S$3 single shift 3 

144 DCS device control string 

145 PU1 private use 1 

146 PU2 private use 2 

147 STS set transmit state 

148 CCH cancel character 

149 MW message waiting 

150 SPA start of protected area 

154 EPA end of protected area 


(continued on next page) 
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Table B—1 (Cont.) DEC Multinational Character Set 


Octal Decimal Char or 
Hex Code Code Code Abbrev. Description 


ASCIli Alpha Characters 


98 230 152 — [reserved] 

99 231 153 — [reserved] 

9A 232 154 — [reserved] 

9B 233 155 CSI control sequence introducer 
9C 234 156 ST string terminator 

9D 235 157 OSC operating system command 
9E 236 158 PM privacy message 

OF 237 159 APC application 

AO 240 160 — [reserved] 

Al 241 161 j inverted exclamation point 
A2 — 242 162 ¢ cent sign 

A3 243 163 £ pound sign 

A4 244 164 — [reserved] 

A5 245 165 ¥ yen sign 

A6 246 166 — [reserved] 

A7 247 167 § section sign 

A8 250 168 a general currency sign 

AQ 251 169 © copyright sign 

AA 252 170 : feminine ordinal indicator 
AB 253 171 « angle quotation mark left 
AC 254 172 — [reserved] 

AD 255 173 — [reserved] 

AE 256 174 — [reserved] 

AF 257 175 — [reserved] 

BO 260 176 = degree sign 

B1 261 177 + plus/minus sign 

B2 262 178 2 superscript 2 

B3 263 179 id superscript 3 

B4 264 180 — [reserved] 

B5 265 181 U micro sign 

B6 266 182 q paragraph sign, pilcrow 
B7 267 183 : middle dot 

B8 270 184 — [reserved] 

B9 271 185 : superscript 1 


(continued on next page) 
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Tables 


Table B-1 (Cont.) DEC Multinational Character Set 


Hex Code 


BA 
BB 
BC 
BD 
BE 
BF 
CO 


Ci 


C2 
C3 
C4 


C5 
Cé 
C7 
C8 


cg 


CA 
CB 


CC 


CD 


CE 
CF 


DO 
D1 
D2 


D3 


Octal Decimal Char or 
Code Code Abbrev. Description 


ASCII Alpha Characters 


272 186 . masculine ordinal indicator 

273 187 » angle quotation mark right 

274 188 V4 fraction one-quarter 

275 189 Va fraction one-half 

276 190 — [reserved] 

277 191 é inverted question mark 

300 192 A uppercase A with grave 
accent 

301 193 A uppercase A with acute 
accent 

302 194 A uppercase A with circumflex 

303 195 A uppercase A with tilde 

304 196 A uppercase A with umlaut, 
(diaeresis) 

305 197 A uppercase A with ring 

306 198 EE uppercase AE diphthong 

307 199 Cc uppercase C with cedilla 

310 200 E uppercase E with grave 
accent 

311 201 E uppercase E with acute 
accent 

312 202 E uppercase E with circumflex 

313 203 E uppercase E with umiaut, 
(diaeresis) 

314 204 ] uppercase | with grave 
accent 

315 205 [ uppercase | with acute 
accent 

316 206 1 uppercase | with circumflex 

317 207 i} uppercase | with umlaut, 
(diaeresis) 

320 208 — [reserved] 

321 209 N uppercase N with tilde 

322 210 O uppercase O with grave 
accent 

323 211 O uppercase O with acute 


accent 


(continued on next page) 
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Table B-1 (Cont.) DEC Multinational Character Set 


Octal Decimal Char or 
Hex Code Code Code Abbrev. Description 


ASCII Alpha Characters 


D4 324 212 fe) uppercase O with circumflex 

D5 325 213 fe) uppercase O with tilde 

D6 326 214 O uppercase O with umlaut, 
(diaeresis) 

D7 327 215 CE uppercase OE ligature 

D8 330 216 4) uppercase O with slash 

D9 331 217 U uppercase U with grave 
accent 

DA 332 218 U uppercase U with acute 
accent 

DB 333 219 U uppercase U with circumflex 

DC 334 220 U uppercase U with umlaut, 
(diaeresis) 

DD 335 221 Y uppercase Y with umlaut, 
(diaeresis) 

DE 336 222 — [reserved] 

DF 337 223 B German lowercase sharp s 

EO 340 224 a lowercase a with grave 
accent 

E1 341 225 a lowercase a with acute 
accent 

E2 342 226 a lowercase a with circumflex 

E3 343 227 a lowercase a with tilde 

E4 344 228 a lowercase a with umlaut, 
(diaeresis) 

E5 345 229 a lowercase a with ring 

E6 346 230 re) lowercase ae diphthong 

E7 347 231 C lowercase c with cedilla 

E8 350 232 é lowercase e with grave 
accent 

E9 351 233 é lowercase e with acute 
accent 

EA 352 234 é lowercase e with circumflex 

EB 353 235 é lowercase e with umlaut, 
(diaeresis) 

EC 354 236 1 lowercase i with grave 
accent 


(continued on next page) 
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Table B-1 (Cont.) DEC Multinational Character Set 


Octal Decimal Char or 
Hex Code Code Code Abbrev. Description 
ASCIil Alpha Characters 

ED 355 237 j lowercase i with acute 
accent 

EE 356 238 i lowercase i with circumflex 

EF 357 239 7 lowercase i with umlaut, 
(diaeresis) 

FO 360 240 — [reserved] 

F1 361 241 fi lowercase n with tilde 

F2 362 242 fe) lowercase o with grave 
accent 

F3 363 243 6 lowercase o with acute 
accent 

F4 364 244 6 lowercase o with circumflex 

F5 365 245 3 lowercase o with tilde 

F6 366 246 6 lowercase o with umlaut, 
(diaeresis) 

F7 367 247 ce lowercase oe ligature 

F8 370 248 7) lowercase o with slash 

FQ 371 249 u lowercase u with grave 
accent 

FA 372 250 u lowercase u with acute 
accent 

FB 373 251 a lowercase u with circumflex 

FC 374 252 a lowercase u with umlaut, 
(diaeresis) 

FD 375 253 y lowercase y with umiaut, 
(diaeresis) 

FE 376 254 — [reserved] 

FF 377 255 — [reserved] 


B.1 Terminal Sequences and Modes 


Table B-2 lists the valid ANSI and Digital-private escape sequences 
for terminals that have the TT2$M_ANSICRT, TT2$M_DECCRT, 
TT2$M_AVO, TT2$M_EDIT, and TT2$M_BLOCK characteristics (see 
Section 8). Table B—2 also lists assumed and selectable ANSI modes 
and selectable Digital-private modes. Only the names of the escape 
sequences and modes are listed (for more information see the specific 
VT100-, VT200-, or VT300- family user’s guide). Unless otherwise 
noted, the operation of escape sequences and modes is identical to the 
particular VT100-, VT200-, or VT300- family terminals that implement 
these features. 


Tables 
B.1 Terminal Sequences and Modes 


Table B~2 Sequences and Modes 
Name Valid Parameters ANSICRT DECCRT AVO_- EDIT BLOCK’ 


ANSI-Defined Escape Sequences 


CPR All X Xx 

CUB All x X 

CUD All x X 

CUF All x Xx 

CUP All X Xx 

CUU All x X 

DSR 0,3,5,6 X X 

ED 0,1,2 x x 

EL 0,1,2 x x 

HVP All X X 

IND x Xx 

NEL X Xx 

Rl X X 

RIS x X 

SCS UK,ASCII,0 x 

SCs UK,ASCII X X 

SGR 0,4,7 X x 

SGR 0,1,4,5,7 4 

DA Terminal specific X 

HTS Xx 

RM Class specific Xx 

SM Class specific Xx 

TBC 0,3 Xx 

DCH All x x 
DL All X X 
IL All x X 


Digital-Private Escape Sequences 


DECDHDL 2,3 X 
DECDWL 6 x 
DECKPAM X 
DECKPNM X 
DECRC 8 Xx 
DECSC, 7 x 


'Terminal characteristics. Prefix is TT2$M_. 
(continued on next page) 
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Tables 


B.1 Terminal Sequences and Modes 


Table B-2 (Cont.) Sequences and Modes 


Name 


DECSTBM 
DECSWL 
DECPRO 
DECTTC 
DECXMIT 


IRM 
GATM 
ERM 


DECCKM 
DECANM 
DECCOLM 
DECSCLM 
DECSCNM 
DECOM 
DECAWM 
DECARM 
DECEDM 
DECEKEM 
DECLTM 
DECSCFDM 
DECTEM 


CRM 
EBM 
ERM 
FEAM 


Valid Parameters ANSICRT DECCRT AVO EDIT 


Digital-Private Escape Sequences 


All x 
5 X 
0,1,4,5,7,254 

0,1 

5 


ANSI Selectable Modes (Set with ANSI SM/RM) 


4 x 


Digital-Private Selectable Modes (Set with ANSI SM/RM) 


1 X 
2 X 
3 Xx 
4 X 
5 Xx 
6 X 
7 Xx 
8 X 
10 
16 
11 
13 
14 
ANSI Assumed Modes 

Reset Reset 

Reset Reset 

Set Set r 

Reset Reset 


'Terminal characteristics. Prefix is TT2$M_. 


2Selectable mode. 


BLOCK’ 


x K KK 


x «KX K K 


(continued on next page) 
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Tables 
B.1 Terminal Sequences and Modes 


Table B-2 (Cont.) Sequences and Modes 
Name Valid Parameters ANSICRT DECCRT AVO- EDIT BLOCK’ 





ANSI Assumed Modes 





FETM Reset Reset 

GATM N/A N/A é 
HEM N/A N/A 

IRM Reset Reset e @ 
KAM Reset Reset 

MATH N/A N/A 

PUM Reset Reset 

SATM N/A N/A 

SRTM Reset Reset 

TSM Reset Reset 

TTM N/A N/A & 
VEM N/A N/A 


1Terminal characteristics. Prefix is TT2$M_. 
2Selectable mode. 
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C Control Connection Routines 


This appendix lists and describes the VAX calling standards for the 
pseudoterminal driver control connection routines. The routines appear in 
this section in alphabetical order. Table C—1 lists the control connection 
routines and their functions. 


Table C—1 Control Connection Routines 


Routine Name Description 

PTD$CANCEL Cancels a queued control connection read 
request 

PTD$CREATE Creates a pseudoterminal 

PTD$DELETE Deletes a pseudoterminal 

PTD$READ Reads data from the pseudoterminal 

PTD$SET_EVENT_NOTIFICATION Enables or disables terminal event notification 
ASTs 

PTDSWRITE Writes data to the pseudoterminal 


PTD$CANCEL 


PTDS$CANCEL Cancel Queued Request 


Cancels a queued control connection read request. 








FORMAT PTD$CANCEL chan 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


ARGUMENTS -~— cha 
VMS usage: channel 
type: word (unsigned) 
access: read only 
mechanism: by value 
Number of the I/O channel assigned to the pseudoterminal. 








RETURN 

V ALU ES SS$_NORMAL ae os completion. 
SS$_DEVOFFLINE Device is off line and request cannot proceed. 
SS$_IVCHAN Illegal channel. . 
SS$_NOPRIV Insufficient privilege to perform request. 


PTDS$CREATE 


PTDSCREATE Create a Pseudoterminal 


Creates a new pseudoterminal with a unique device name. 








FORMAT PTD$CREATE chan [,acmode] [, charbuff] [, buflen] 
[,astadr] [astprm] [,ast_acmode], inadr 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 





ARGUMENTS ~~ chan 
VMS usage: channel 
type: word (unsigned) 
access: write only 
mechanism: by reference 
Number of the channel that is assigned to the new pseudoterminal. This 
argument is the address of a word into which PTD$CREATE writes the 
channel number. 


acmode 

VMS usage: access_mode 

type: longword (unsigned) 

access: read only 

mechanism: by value 

Access mode to be associated with the channel. The most privileged access 
mode is the access mode of the caller. I/O operations on the channel can 
be performed only from equal and more privileged access modes. 


charbuff 


VMS usage: device_characteristics 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Address of buffer containing the device characteristics. This information is 
used to set up the pseudoterminal’s initial characteristics. This buffer can 
be 12, 16, or 20 bytes long. 


Figure C—1 shows the format of this buffer. 
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PTD$CREATE 


Figure C—1 Device Characteristics Buffer 


ZK-9573-GE 







buflen 

VMS usage: word_unsigned 
type: word (unsigned) 
access: read only 


mechanism: by value 
Length of the characteristics buffer (either 12, 16, or 20 bytes), This 
argument is required if you supply the charbuff argument. 


astadr 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 

AST service routine to be executed when the terminal connection deassigns 
the last channel to the pseudoterminal. This argument is the address of 
the entry mask of this routine. This is a repeating AST and is active until 
the control connection deletes the pseudoterminal. 


astprm 

VMS usage: user_arg 

type: longword (unsigned) 
access: read only 


mechanism: by value 


AST parameter to be passed to the AST service routine specified by 
astadr. 


ast_acmode 


VMS usage: access mode 

type: longword (unsigned) 

access: read only 

mechanism: by value 

Access mode for which the AST is to be declared. The most privileged 
access mode is the access mode of the caller. The resulting mode is the 
access mode at which the AST is declared. 


PTD$CREATE 


inadr 

VMS usage: address _ range 

type: longword (unsigned) 
access: read only 


mechanism: by reference 

Address of a two-longword array containing the starting and ending 
virtual address in the virtual address space of the process (either PO 

or Pl regions) to be used as I/O buffers. The array contains, in order, 
the starting and ending virtual addresses. The address must specify an 
integral number of pages; that is, the low-order nine bits of each address 
must be 0. The pages must already exist and must be fully contained in 
either PO or Pl space. All pages in the range must: 


¢ Have identical page protection 

¢ Be writable in the mode of the caller 

¢ Be owned by the same access mode 

¢ Be owned in a mode equal to or less privileged than the caller 


¢ Be of the same page type (process or global) 





DESCRIPTION 


PTD$CREATE creates a new pseudoterminal with a unique device name. 
This device name is in the form FTAn:, where n is the unit number. This 
unit number is a VMS channel number that is used for control operations. 


When a pseudoterminal is created, it inherits the current system terminal 
default attributes unless you specify an alternate set of characteristics. 





RETURN 
VALUES 


SS$_NORMAL Normal successful completion. 
SS$_ACCVIO Unable to read one of the arguments. 
SS$_BADPARAM Bad parameter value. 

SS$_EXBYTLM Insufficient BYTLM to create device or map buffers. 
SS$_EXQUOTA Insufficient quota to create device. 
SS$_EXASTLM Insufficient AST quota for notification AST. 
SS$_INSFMEM Insufficient memory to create device. 
SS$_INSFWSL Insufficient working set limit to map buffers. 
SS$_IVSECFLG Invalid process or global section flags. 
SS$_NOPRIV No privilege for attempted operation. 
SS$_PAGOWNVIO Page owner violation. 

SS$_VA_IN_USE Virtual address already in use. 
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PTD$DELETE 


PTD$S$DELETE Delete a Pseudoterminal 


Forces the pseudoterminal to be deleted and frees the channel. 








FORMAT PTD$CANCEL chan 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 





ARGUMENTS ~~ chan 
VMS usage: channel 
type: word (unsigned) 
access: read only 
mechanism: by value 
Number of the I/O channel assigned to the pseudoterminal. 





DESCRIPTION PID$DELETE forces the pseudoterminal to be deleted and frees the 
channel assigned to the pseudoterminal. When a pseudoterminal is 
deleted, any process using the pseudoterminal (except the control program) 
is disconnected. PTD$DELETE request causes any pending I/O for the 
control program to be aborted. It deletes any queued event notification 
ASTs and returns the I/O buffers back to the application. It also causes the 
pseudoterminal unit control block (UCB) to be deleted once the reference 
count returns to zero. 





RETURN . 

VALUES SS$_NORMAL peat Suge completion. 
SS$_DEVOFFLINE Device is off line and request cannot proceed. 
SS$_IVCHAN Illegal channel. 
SS$_NOPRIV Insufficient privilege to perform request. 


PTDSREAD 


PTDSREAD Read Data from Pseudoterminal 


Reads data from the pseudoterminal. 











FORMAT PTD$READ [efn], chan [,astadr] [,astorm] readbut, 
readbuf_len 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
ARGUMENTS _~ efn 
VMS usage: ef_number 
type: longword (unsigned) 
access: read only 


mechanism: by value 

Number of the event flag to be set when PTD$READ returns the requested 
information. If you do not specify this argument, event flag 0 is used. 
When PTD$READ begins execution, it clears this flag. 


chan 

VMS usage: channel 

type: word (unsigned) 
access: read only 


mechanism: by value 
Number of the I/O channel assigned to the pseudoterminal. 


astadr 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 

AST service routine to be executed when PTD$READ completes. If you 
specify astadr, the AST routine executes at the same access mode as the 
caller of the PTD$READ routine. 


astprm 

VMS usage: user_arg 

type: longword (unsigned) 
access: read only 


mechanism: by value 
AST parameter to be passed to the AST service routine specified by the 
astadr argument. 
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PTDS$READ 


readbuf 


VMS usage: char_string 

type: character coded text string 

access: write only 

mechanism: by reference 

Address of the read I/O status longword. The first character position in 
an I/O buffer to receive all output is this address plus 4. The readbuf 
argument must be in the range specified in the inadr argument of the 
PTD$CREATE routine, otherwise an SS$_ACCVIO status is returned. 


readbuf_len 


VMS usage: word_unsigned 

type: word (unsigned) 

access: read only 

mechanism: by value 

Number of characters that can be read from the pseudoterminal and 
stored in the buffer specified by readbuf. The low-order nine bits of the 
starting address plus readbuf_len must be less than or equal to 508. 
SS$_IVBUFLEN is returned if the value of readbuf_len is less than 0 or 
more than 508. 





DESCRIPTION 


The PTD$READ routine reads data from the pseudoterminal. The read 
request completes with a minimum of one character and a maximum of the 
number of characters specified by the readbuf_len argument. The read 
operation completes when the pseudoterminal has characters to output. 

If a read request is issued and no data is available, the read request is 
queued and then completed at a later time. 





RETURN 
VALUES 


SS$_NORMAL Normal successful completion. 

SS$_ACCVIO Unable to read an argument, or invalid read buffer 
address. 

SS$_DEVOFFLINE Device is off line and request cannot proceed. 

SS$_EXASTLM Insufficient AST quota for notification AST. 

SS$_ILLEFC Illegal event flag cluster. 

SS$_INSFMEM Insufficient memory. 

SS$_IVBUFLEN Buffer size supplied is illegal. 

SS$_IVCHAN illegal channel. 

SS$_NOPRIV Insufficient privilege to perform request. 

SS$_UNASEFC Unassociated event flag cluster. 


PTD$SET_EVENT_NOTIFICATION 


PTD$SET_EVENT_NOTIFICATION Enable or Disable 


Terminal Event 
Notification ASTs 


Enables or disables a number of repeating terminal event notification ASTs. 





FORMAT 


PTD$SET_EVENT_NOTIFICATION chan, astadr 


[,astorm] 
[,acmode], type 





VMS usage: 
type: 
access: 
mechanism: 


RETURNS 


cond_value 
longword (unsigned) 
write only 

by value 





ARGUMENTS '~— chan 
VMS usage: 
type: 
access: 
mechanism: 


channel 

word (unsigned) 
read only 

by value 


Number of the I/O channel assigned to the pseudoterminal. 


astadr 
VMS usage: 
type: 
access: 
mechanism: 


ast_procedure 

procedure entry mask 

call without stack unwinding 
by reference 


Address of the notification AST service routine, or zero if the AST is to be | 


canceled. 


astprm 
VMS usage: 
type: 
access: 
mechanism: 


user_arg 

longword (unsigned) 
read only 

by value 


AST parameter to be passed to the AST service routine specified by the 
astadr argument. 


acmode 
VMS usage: 
type: 
access: 
mechanism: 


access_mode 
longword (unsigned) 
read only 

by value 
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PTDS$SET_EVENT_NOTIFICATION 


Access mode for which the AST is to be declared. The most privileged 
access mode is the access mode of the caller. The resulting mode is the 
access mode at which the AST is declared. 


type 


VMS usage: type_longword 


type: 
access: 


longword (unsigned) 
read only 


mechanism: by value 
Value that indicates which notification AST to enable. The $PTDDEF 
macro defines the symbolic names listed in Table C-2. 


Table C-2 Symbolic Names Defined by $PTDDEF Macro 


Symbolic Name 


PTD$C_SEND_XON 
PTD$C_SEND_BELL 
PTD$C_SEND_XOFF 


PTD$C_STOP_OUTPUT 
PTD$C_RESUME_OUTPUT 
PTD$C_CHAR_CHANGED 


PTD$C_ABORT_OUTPUT 
PTD$C_START_READ 


PTD$C_MIDDLE_READ 


PTD$C_END_READ 
PTD$C_ENABLE_READ 


PTD$C_DISABLE_READ 


Description 
Deliver notification AST when pseudoterminal is ready to accept input. This AST 
is not delivered if the pseudoterminal is set to NO HOSTSYNC. 


Deliver notification AST when pseudoterminal wants to stop input and signal it with 
a bell character. 


Deliver notification AST when pseudoterminal wants to stop input and signal it with 
a DC3 character. 


Deliver notification AST when pseudoterminal is stopping output. 
Deliver notification AST when pseudoterminal is resuming output. 


Deliver notification AST when pseudoterminal has changed some device 
characteristic. 


Deliver notification AST when pseudoterminal wants to abort output. 


Deliver notification AST when pseudoterminal is starting an application’s read 
request. This AST is delivered only if read event notification has been enabled. 


Deliver notification AST when pseudoterminal has finished sending an application’s 
read request prompt string. This AST is delivered only if read event notification 
has been enabled. 


Deliver notification AST when pseudoterminal has finished an application’s read 
request. This AST is delivered only if read event notification has been enabled. 


Enable terminal read event AST delivery. If this code is used, you cannot supply 
the astadr argument. 


Disable terminal read event AST delivery. If this code is used, you cannot supply 
the astadr argument. 





DESCRIPTION 


PTD$SET_EVENT_NOTIFICATION enables or disables the repeating 


terminal event notification ASTs listed in Table C—2. Once an event 
notification AST in enabled, it remains in effect until it is disabled or until 
the device is deleted. 
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PTD$SET_EVENT_NOTIFICATION 





RETURN SS$_NORMAL N | ful leti 
ormal successful completion. 
VALUES = denen 
SS$_ACCVIO Unable to read an argument, or invalid I/O buffer 
address. 
SS$_BADPARAM An astadr, astprm, or acmode argument was not 
zero when enabling or disabling read notification. 
SS$_DEVOFFLINE Device is off line and request cannot proceed. 
SS$_EXASTLM Insufficient AST quota for notification AST. 
SS$_INSFMEM Insufficient memory. 
SS$_IVCHAN Illegal channel. 
SS$_NOPRIV Insufficient privilege to perform request. 
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PTDSWRITE 


PTDSWRITE Write Data to Pseudoterminal 


Inputs data to the pseudoterminal and reads any immediately echoed 
characters. 








FORMAT PTDSWRITE chan [,astadr] [,astorm], wrtbuf, 
wrtbuf_len [,echobuf] [,echobuf_len] 

RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 
ARGUMENTS -~ chan 

VMS usage: channel 

type: word (unsigned) 

access: read only 
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mechanism: by value 
Number of I/O channel assigned to the pseudoterminal. 


astadr 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 

AST service routine to be executed when PTD$WRITE completes. If 
astadr is specified, the AST routine executes at the same access mode as 
the caller of the PTD$WRITE routine. 


astprm 

VMS usage: user_arg 

type: longword (unsigned) 
access: read only 


mechanism: by value 
AST parameter to be passed to the AST service routine specified by the 
astadr argument. 


wrtbuf 

VMS usage: char_string 

type: character coded text string 
access: read only 


mechanism: by reference 

Address of the write I/O status longword. The first character in an I/O 
buffer to be written is this address plus 4. The wrtbuf must be in the 
range specified by the inadr argument of the PTD$CREATE routine; 
otherwise an SS$_ACCVIO status is returned. 


PTDSWRITE 


wrtbuf_len 


VMS usage: word_unsigned 

type: word (unsigned) 

access: read only 

mechanism: by value 

Number of characters to be written to the pseudoterminal. These 
characters appear as input to the terminal side of the pseudoterminal. 
The low-order nine bits of the starting address plus wrtbuf_len must 
be less than or equal to 508. SS$_IVBUFLEN is returned if the value of 
wrtbuf_len is less than 0 or more than 508. 


echobuf 


VMS usage: char_string 

type: character coded text string 

access: write only 

mechanism: by reference 

Address of the echo I/O status longword. The first character position in an 
I/O buffer to receive all output is this address plus 4. The echobuf must 
be in the range specified by the inadr argument of the PTD$CREATE 
routine; otherwise an SS$_ACCVIO status is returned. 


echobuf_len 


VMS usage: word_unsigned 

type: word (unsigned) 

access: read only 

mechanism: by value 

Number of characters that can be read from the pseudoterminal. If an 
echo buffer is specified, up to echobuf_len characters can be stored in it. 
The low-order nine bits of the starting address plus echobuf_len must be 
less than or equal to 508. SS$_IVBUFLEN is returned if 0 characters or 
more than 508 characters are specified. 








DESCRIPTION $PTDS$WRITE inputs data to the pseudoterminal and reads any 
immediately echoed characters. PTD$WRITE allows you to specify a 
buffer to receive any output generated by the write; you do not need to 
issue a separate read request to read this data. 

RETURN SS$_NORMAL N ful leti 

ormal successful completion. 

VALUES : Lane 

SS$_ACCVIO Unable to read an argument, or invalid !/O buffer 
address. . 

SS$_DATALOST The terminal driver type-ahead buffer is full and 
character written was lost. 

$S$_DATAOVERUN The terminal driver type-ahead buffer is getting full; 
attempts to send more data might result in loss of 
characters. 

SS$_DEVOFFLINE Device is off line and request cannot proceed. 

SS$_EXASTLM Insufficient AST quota for notification AST. 


PTDSWRITE 
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SS$_INSFMEM 
SS$_IVBUFLEN 
SS$_IVCHAN 
SS$_NOPRIV 


Insufficient memory. 

Buffer size supplied is illegal. 

illegal channel. 

Insufficient privilege to perform request. 


Index 





A 


ACP control function « 1-30 
disk quotas * 1-33 
magnetic tape positioning * 1-31 
miscellaneous disk » 1-32 
quota file transfer block * 1-33 
ACP function « 1-2 
arguments * 1-2 
attributes 1-16 to 1-18 
1IO$_ ACCESS « 1-7, 1-10, 1-14, 1-26 
1IO$_ACPCONTROL « 1-7, 1-30 
lO$_CREATE « 1-10, 1-11, 1-14, 1-22 
IO$_DEACCESS * 1-13, 1-14, 1-28 
1IO$_DELETE » 1-7, 1-29 
lIO$_MODIFY « 1-7, 1-11, 1-13, 1-14, 1-28 
lIO$_MOUNT « 1-30 
major * 1-22 
ACP-QIO interface 
access file function * 1-26 
access subfunction + 1-10 
ACP control function * 1-30 
ANSI standard « 1-2, 1-32 
arguments « 1-2 
disk quota * 1-33 
attribute control block * 1-14 
attributes * 1-16 to 1-18 
attributes statistics block * 1-21 
BLISS-32 programming « 1-2 
create file function » 1-22 
disk * 1-24 
magnetic tape * 1-26 
deaccess file function * 1-28 
delete file function * 1-29 
description + 1-1 
directory entries * 1-9, 1-26 
FIB (file information block) « 1-3 
See also FIB (file information block) 
file characteristics * 1-18 
function codes « A—1 
function modifiers « 1-2 
IO$M_ACCESS °« 1-10, 1-23, 1-25, 1-26 
lIO$M_CREATE ¢ 1-23, 1-24, 1-25, 1-26 
IO$M_DELETE ¢ 1-23, 1-24, 1-30 
IO$M_DMOUNT « 1-31, 1-32 
I/O operations « 1-1 


ACP-QIO interface (Cont.) 


I/O status block « 1-35 
record attributes area» 1-19 
values * 1-20 

serious exception (EOT) * 1-23, 1-27, 1-32 

status returns * A—1 

VAX MACRO programming « 1-1 

XQP (extended QIO processor) « 1-1 
ACP subfunction * 1-7 

access ° 1-10 

directory lookup « 1-7 

extend ¢ 1-11, 1-35 

read/write attributes * 1-14 

truncate «1-13 
ALTMODE key ¢ 8-21 
ANSI escape sequence * B—9 
Application programs 

connecting to LAT ports * 8-48 


Argument 
device- or function-dependent * 1~2 
liste A—1 to A-9 


LPA11-K subroutine * 4-16 
ASCII (8-bit) code * 2-8 
ASCII character set 
See DEC Multinational Character Set 
AST (asynchronous system trap) 
quota * 3-24, 4-14, 6-13, 7-5, 8-43 
Asynchronous SCSI data transfer mode 
enabling * 11-7, 11-13 
Attention AST 
mailbox * 7-9 
terminal * 8-42 
Autoconfiguration 
of SCSI device * 11-9 


Batch job command procedure 

using a card reader * 2—2 
Baud rate 

terminal « 8—40 
BOT (beginning-of-tape) 

See Magnetic tape, BOT marker 
Broadcast message * 8-18, 8-21, 8-23, 8-46 
Buffered I/O quota * 3-24, 6-13, 7-5 
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Buffer overrun 
with LPA11-K * 4-12 


C 


Cache 
tape * 6-8 
write-back volatile * 6-8 
Card reader 
card punch combinations » 2—1 
026 card reader code * 2—2, 2-8 
029 card reader code « 2-2, 2-8 
code « 2-8 
device characteristics » 2-5 
driver * 2—1 
end-of-file status » 2-2 
error recovery * 2-3 
failure categories * 2-4 
features * 2—1 
for batch job command procedures * 2-2 
function codes * 2-5, A-2 
function modifiers 
1O$M_BINARY * 2-1, 2-6 
IO$M_PACKED « 2-1, 2-6 
/O functions 
1O$_READLBLK * 2-6 
lO$_READPBLK « 2-6 
1O$_READVBLK « 2-6 
1O$_SENSEMODE « 2-7 
1O$_SETCHAR « 2-10 
1O$_SETMODE « 2-8 
/O status block * 2—11 
read function * 2-6 
read modes « 2—1 
sense mode function * 2—7 
set mode function * 2-7 
set translation mode * 2-2 
status returns * A-2 
supported device « 2—1 
SYS$GETDVI returns * 2-5 
Carriage control 
line printer « 5-6 
terminal * 8-36 
CDROM 
See Disk 
Character 
formatting on line printer * 5-2 
terminal terminator * 8-28 
Character set 
See DEC Multinational Character Set 
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Character set (Cont.) 
terminal lowercase ¢ 8-21 
Clock rate 
with LPA11-K * 4—10 
Compact Disc Read-Only Memory (CDROM) 
See Disk 
CONNECT command ¢ 8-17 
Console disk 
See RX01 console disk 
Console terminal * 8—1 
Control character 
list * B—1 
terminal » 8-4 to 8-6, 8-9 
Control connection routines »* C—1 
PTD$CANCEL + C-2 
PTD$CREATE *« C-3 
PTD$DELETE * C-6 
PTD$READ « C—7 
PTD$SET_EVENT_NOTIFICATION + C-9 
PTD$WRITE « C—12 
Control sequence 
terminal * 8-8 
Create file function * 1-22 
directory entry creation * 1-26 
CTDRIVER « 8—11, 8-35 
CTRL/x 
See Terminal, control characters 


D 


Data buffer, LPA11-K * 4—14 

Data check 
disk * 3-15, 3-29, 3-30 
magnetic tape * 6-8, 6-17, 6-18 

Data security erase 
magnetic tape * 6-27 

Data transfer command table 
LPA11-K * 4-11 

Data transfer mode 
as controlled by the generic SCSI class driver + 

11-7, 11-13 

asynchronous « 11-7, 11-13 
synchronous * 11-7, 11-13 

Data transfer start command 
LPA11-K* 4-12 

Data transfer stop command 
LPA11-K * 4-14 

Data underrun/overrun 
with LPA11-K * 4-12 

Deaccess file function * 1-28 





DEC026 card reader code « 2—2, 2-8 
DEC029 card reader code « 2—2, 2-8 
DEC Multinational Character Set * B—1 
Delete file function » 1-29 
DELETE key » 8—4 
Device characteristics 
card reader ¢ 2-5 
disk * 3-22 
line printer » 5-3 
LPA11-K device « 4—5 
magnetic tape * 6—11 
mailbox « 7—4 
pseudoterminal * 9-3 
terminal « 8-20 
DHU11 device * 8—1 
DHV11 device * 8—1 
Dial-up line «8-13 
Digital-private escape sequence » B—-9 
Direct I/O quota * 3-24, 6-13 
Directory entry 
creation * 1-26 
protection * 1-9 
Directory lookup subfunction » 1-7 
directory entry protection « 1-9 
DISCONNECT command « 8-17 
Disconnect feature 
enabling * 11-13 
Disk 
See also DSA disk 
ACP control function * 1-32 
ACP operation 
creating file » 1-24 
deaccessing file * 1-28 
available function * 3-33 
Backup Utility » 3-21 
compact disc * 3-8 
data check « 3-15, 3-29, 3-30 
device characteristics * 3-22 
driver * 3—1 
SCSI ¢ 3-22 
VAXstation 2000 and MicroVAX 2000 « 3-21 
dual-pathed « 3-11 
DSA disks * 3-14 
dual-ported * 3-12 
dual porting 
DSA disks * 3-14 
HSC disks * 3-15 
restrictions for use » 3-13 
error recovery * 3-17 
features * 3-11 
file attributes « 3-16 
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Disk (Cont.) 


function codes * 3-25, A-2 

function modifiers 
lIO$M_DATACHECK « 3-15, 3-29, 3-30 
lIO$M_DELDATA « 3-30 
lO$M_ERASE « 3-27, 3-31 
lO$M_INHRETRY * 3-17, 3-29, 3-30 

HSC40 controller » 3-3 

HSC50 coniroller * 3-3 

HSC70 controller « 3-3 

I/O functions * 3-24 
See also ACP-QIO interface 
arguments 3-26 to 3-29 
lO$_ACPCONTROL « 1-32 
1O$_AVAILABLE « 3-33 
10$_FORMAT « 3-31 
1O$_PACKACK « 3-32 
lO$_READLBLK « 3~29 
lIO$_READPBLK ¢ 3-29 
1O$_READVBLK ¢ 3-29 
1O$_SEARCH « 3-31 
lO$_SEEK + 3-33 
lO$_ SENSECHAR « 3-31 
lO$_ SENSEMODE « 3-31 
1O$_SETPRFPTH « 3-34 
lIO$_UNLOAD « 3-32 
lO$_WRITECHECK « 3-33 
lO$_WRITELBLK « 3-30 
1O$_WRITEPBLK « 3-30 
10$_WRITEVBLK « 3-30 

I/O status block «3-36 

KDAS5O controller » 3-3 

KDBS50 controller * 3-3 

KFQSA adapter + 3-5 

offset recovery * 3-16 

pack acknowledge function * 3-32 

port access mode * 3-12 

port selection * 3-12 

programming example * 3-37 

quotas 1-33 to 1-34, 3-24 

RA60 « 3-5 

RA70 « 3-5 

RA90 « 3-5 

RBO2 « 3-6 

RC25 * 3-6 

RCT (replacement and caching table) * 3-20 

RD53 + 3-6 

RD54 «3-6 

read function * 3-29 

RF30 * 3-7 
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Disk (Cont.) 
RF31 
failover * 3-15 
RF70 
failover * 3-15 
RF71 * 3-7 
RMO3 « 3-7 
RMO5 ¢ 3-7 
RP0O5 * 3-7 
RP06 « 3—7 
RPO7 ¢ 3-7 
RQDX3 controller * 3-5 
RRD40 CDROM «3-8 
RRD50 CDROM « 3-8 
RX02 * 3-8 
RX06 cartridge * 3-7 
RX07 cartridge * 3-7 
RX23 flexible » 3-9 
RX33 flexible «3-10 
RX50 flexible » 3-10 
RZ22 «3-10 
RZ23 «3-10 
RZ55 * 3-10 
SDI + 3-5 
search function * 3-31 
sector translation * 3-18 
seek operations * 3-16, 3-33 
sense mode function * 3-31 
set density function * 3-31 
set preferred path function » 3-34 
SII integral adapter » 3-4 
skip sectoring ¢ 3-17 
status returns * A-3 
supported devices * 3-1 to 3-11 
SYS$GETDVI returns * 3-22 
TU58 magnetic tape * 3-10, 3-16, 3-29, 3-30, 
3-31, 3-33 
UDASO disk adapter + 3-3 
unload function * 3-32 
use with Verify Utility 3-19, 3-21 
VAXstation 2000 and MicroVAX 2000 driver * 3-21 
write check function * 3-33 
write function * 3-30 
Disk class driver 
disabling the loading of «11-10 
Disk drive 
compatibility for volume shadowing « 10-3 
DISMOUNT command « 1-32 
DMB32 device + 8-1 
DMF832 device * 8-1 
DMZ32 device « 8—1 
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Driver 
card reader « 2—1 
disk » 3-1 
LAT port * 8—1 
line printer * 5—14 
LPA11-K device * 4—1 
magnetic tape » 6-1 
mailbox * 7—1 
pseudoterminal « 9—1 
SCSI + 3-22 
shadow set virtual unit * 10-1 
terminal * 8—1 
VAXstation 2000 and MicroVAX 2000 disk * 3-21 
DSA (DIGITAL Storage Architecture) 
See DSA disk 
DSA32 device « 8-1 
DSA disk «3-1, 3-14 
See also Disk 
bad block « 3-19, 3-21 
bad block replacement * 3-20, 3-21 
forced error * 3-20 
forced error flag * 3-21 
use with Verify Utility 3-19, 3-21 
Dual host 
definition of «3-4 
Dual path 
definition of * 3-11 
Dual-pathed disk * 3-11 
DSA disk ¢ 3-14 
Dual-ported disk * 3-12 
DSA disk « 3-14 
HSC disk * 3-15 
restrictions for use * 3-13 
Duplex mode 
See also Half-duplex mode 
terminal * 8-10 
DZ11 device « 8—1 
DZ32 device * 8-1 
DZV11 device * 8—1 


E 


End-of-file 
See EOF 
End-of-tape 
See EOT 
End-of-volume 
detection on magnetic tape * 6-20 





EOF (end-of-file) 
status 
card reader * 2-2 
magnetic tape * 6—17 
write mailbox message « 7-9 
EOJ command 
in card reader batch job »* 2-2 
EOT (end-of-tape) 
status 
magnetic tape * 6-17, 6-19, 6-21 
Error recovery 
disk * 3-17 
line printer * 5~3 
magnetic tape * 6-9 
shadow set virtual unit driver * 10-9 
Escape sequence 
ANSI + B-9 
Digital-private « B—9 
terminal « 8-7, 8-21 
Event notification 
pseudoterminal * 9-6 
Extend subfunction * 1-11 


-E 


FIB (file information block) « 1-3 
See also ACP function 
access control « 1-10 
contents «1-5 to 1-7 
descriptor « 1-2, 1-3 
directory lookup * 1-8 
disk quota* 1-33 to 1-34 
extend control * 1-11 
format 1-5 
IO$_ACCESS « 1-26 
lO$_ACPCONTROL * 1-31 to 1-34 
1IO$_CREATE « 1-23 
lO$_DEACCESS « 1-28 
1O$_DELETE « 1-30 
1O$_MODIFY « 1-29 
truncate control « 1-13 

File characteristics 
ACP-QIO attributes * 1-18 

Floppy disk 
See Diskette 

Form feed 
line printer * 5-4 
mechanical * 5-4 
terminal * 8-21 
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Full-duplex mode « 8-10 

Function code 
See also I/O function 
1O$_ACCESS « 1-26 
lO$_ACPCONTROL « 1-30, 6-15 
1O$_ADDSHAD « 10-5 
1IO$_AVAILABLE + 3-33, 6-27, 10-8 
lO$_COPYSHAD « 10-6 
1O$_CREATE « 1~22 
lO$_CRESHAD « 10-4 
1O$_DEACCESS * 1-28 
lO$_DELETE « 1-29 
1IO$_DSE * 6-27 
lIO$_FORMAT « 3-31 
1O$_INITIALIZE + 4-9 
l1O$_LOADMCODE « 4-8 
lO$_MODIFY « 1-28 
1O$_PACKACK « 3-32 
1O$_READLBLK ¢ 2-6, 3-29, 6-17, 7-5, 8~-26 
1O$_READPBLK «2-6, 3-29, 6-17, 7-5 
lO$_READPROMPT « 8-26 
lIO$_READVBLK ¢ 2-6, 3-29, 6-17, 7-5, 8-26 
lO$_REMSHAD « 10-7 
IO$_REWIND « 6-19 
l1O$_REWINDOFF « 6-21 
lIO$_SEARCH « 3-31 
lO$_SEEK ¢ 3-33 
IO$_SENSECHAR ¢ 3-31, 8-53, 10-8 
lIO$_SENSEMODE ° 2-7, 3-31, 5-9, 6-22, 8-53 
1O$_SETCHAR ¢ 2-10, 5-9, 6-23, 8-38 
lO$_SETCLOCK « 4-10 
1O$_SETMODE ¢ 2-8, 5-9, 6-23, 8-38 
10$_SETPRFPTH « 3-34 
1O$_SKIPFILE « 6-19 
10$_SKIPRECORD « 6-20 
lO$_STARTDATA ¢ 4-11 
1O$_UNLOAD « 3-32, 6-22 
lO$_WRITECHECK ¢ 3-33 
1O$_WRITELBLK « 3-30, 5-5, 6-18, 7-6, 8-34 
l1O$_WRITEOF ¢ 6-21 
lO$_WRITEPBLK « 3-30, 5-5, 6-18, 7-6, 8-34 
lO$_WRITEVBLK ¢ 3-30, 5-5, 6-18, 7-6, 8-34 
list of e A—1 to A~9 

Function modifier 
IO$M_ACCESS * 1-23, 1-26, 6-13 
lIO$M_BINARY «+ 2-6 
IO$M_BRDCST « 8-46, 8-55 
lIO$M_BREAKTHRU « 8-10, 8-35 
IO$M_CANCTRLO « 8-5, 8-35 
IO$SM_CREATE ° 1-23, 1-26, 6-13 
lO$M_CTRLCAST « 8-42 


Index—5 


Index 


Function modifier (Cont.) 
IO$M_CTRLYAST « 8-5, 8-42 
IO$SM_CVTLOW « 8-27 
lO$M_DATACHECK « 3-15, 3-29, 3-30, 6-8, 

6-17, 6-18 
1O$M_DELDATA « 3-30 
lO$M_DELETE « 1-23, 1-30 
lIO$M_DMOUNT ° 1-31 
IO$M_DSABLMBxX ¢ 8-27 
IO$M_ENABLMBxX « 8-35 
IO$M_ERASE « 3-27, 3-31, 6-18 
IO$M_ESCAPE « 8-7, 8-27 
lO$M_EXTEND « 8-27, 8-29 
IO$M_HANGUP « 8-42 
IO$M_INCLUDE « 8-43, 8-46 
1O$M_INHEXTGAP « 6-10 
lIO$M_INHRETRY « 3-29, 6-9 
IO$M_MAINT « 8-44, 8-45 
IO$SM_NOECHO « 8-10, 8-24, 8-27 
IOSM_NOFILTR ¢ 8-27 
1IO$M_NOFORMAT ¢ 8-11, 8-35 
\O$SM_NORSWAIT ¢ 7-7 
IO$SM_NOW ¢ 7-6, 7—7 
IO$M_NOWAIT + 6-19, 6-21, 6-22 
IO$M_OUTBAND « 8-46 
lIOSM_PACKED « 2-6 
|\O$M_PURGE « 8-27 
lIO$M_RD_MODEM « 8-54 
lIO$M_READATTN « 7-9 
lIO$M_REFRESH « 8-36 
IO$GM_REVERSE « 6-17 
IO$M_SETEVF « 4-11 
IO$M_SETPROT « 7—11 
lIO$M_SET_MODEM ¢ 8-44 
1O$M_TIMED + 8-27 
lIO$M_TRMNOECHO « 8-28 
1O$M_TT_ABORT « 8-46 
IO$SM_TYPEAHDCNT « 8—54 
IO$M_UNLOOP « 8-45 
list of * A-1 to A-9 


G 


Generic SCSI class driver* 11-1 to 11-16 
assigning a channel to * 11-10 
flow of» 11-4 to 11-6 
I/O status block returned by « 11-11 
loading * 11-9 
obtaining device information from * 11-14 
programming example * 11-15 to 11-16 
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Generic SCSI class driver (Cont.) 


$QIO system service format for* 11-11 to 11-14 
security considerations * 11-6 

Generic SCSI descriptor 
format of * 11-12 to 11-14 


H 


Half-duplex mode « 8-10, 8-21 


See also Duplex mode 
Hang up 

function modifier » 8-42 

terminal « 8-18, 8-24 
HSC40 disk controller * 3-3 
HSC50 disk controller * 3—3 
HSC70 disk controller « 3-3 
HSC disk «3-15 





/O buffers 
pseudoterminal * 9-4 
/O function 
See also Function code 
ACP-QIO interface « 1-2 
card reader * 2-5 
codes * A—1 
disk * 1-2, 3-24 
line printer » 5-5 
list of A~1 to A-9 
LPA11-K device * 4~—8 
magnetic tape * 1-2, 6-13 
terminal * 8-26 
I/O status block 
ACP-QIO interface * 1-35 
card reader « 2—11 
disk * 3-36 
LAT port driver * 8-56 
line printer * 5-10 
LPA11-K device * 4-33 
magnetic tape » 6-28 
mailbox * 7-12 
returned by generic SCSI class driver * 11-11 
terminal « 8-56 
INITIALIZE command * 6-27 
Initialize command table 
LPA11-K device » 4-9 
ltemlist read operations * 8-29 





J 


JOB command 
in card reader batch job * 2-2 


K 


KDAS0O disk controller * 3-3 

KDB50 disk controller » 3-3 

Keyboard control character * 8-4 to 8-6, 8-9 
KFQSA adapter « 3-5 


L 


Laboratory Peripheral Accelerator 
See LPA11-K device 
LAT port driver (LTDRIVER) « 8—1 
Line printer 
carriage control * 5-6, 5-8 
character case * 5—4 
character formatting « 5-2 
device characteristics * 5-3 
driver « 5—1 
error recovery * 5-3 
form feed « 5-4 
function codes « 5-5, A-5 
1/O functions 
1O$_SENSEMODE «5-9 
1O$_SETCHAR « 5-9 
lO$_SETMODE «5-9 
1O$_WRITELBLK « 5-5 
lIO$_WRITEPBLK « 5-5 
1O$_WRITEVBLK « 5-5 
1/O status block « 5-10 
printall mode + 5—4 
programming example « 5-11 
sense mode function * 5-9 
set characteristics * 5~9 
set mode function * 5-9 
status returns * A-5 
supported devices * 5—1 
SYS$GETDVI returns « 5-3 
write function « 5-5 
carriage control * 5-6 
Line terminator 
terminal » 8—9 
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LPA11-K device 
AST 
address * 4-12, 4-14 
quota * 4-14 
synchronization * 4-14 
buffer management * 4-16 
buffer overrun * 4-12, 4-14, 4-31 
buffer queue control * 4-16 
clock rate « 4-10 
data buffer + 4-14 
data sampling « 4—1 
data transfer command table ¢ 4-11 
data transfer start command ¢ 4-12 
data transfer stop command « 4-14 
data underrun/overrun ¢ 4—12 
device characteristics *4-5 to 4-8 
device configuration * 4~2, 4-10, 4-34 
device initialization * 4-4, 4-8 to 4-9, 4-32, 4-34 
driver * 4—1 
errors * 4—2 
features * 4-3 
function codes * 4-8, A-4 
function modifier 
IOSM_SETEVF « 4-11, 4-14 
high-level language support routines * 4—15 
I/O functions 
IO$_INITIALIZE * 4-9 
10$_LOADMCODE « 4~8 
1O$_SETCLOCK « 4-10 
l\O$_STARTDATA ¢ 4—11 
lO$_STARTMPROC ¢ 4-9 
I/O status block * 4—33 
initialize command table » 4—9 
initialize function « 4-9 
load microcode function « 4-8 
maintenance status register * 4—10, 4-33 
microcode loading * 4—4, 4—8, 4-32, 4-34 
modes of operation « 4—1 
operator process ¢ 4—35 
programming examples « 4-37, 4-39, 4-44 
RSX-11M/M—PLUS and VMS differences + 4-35 
set clock function * 4-10 
start data transfer request function « 4—11 
start microprocessor function « 4—9 
status returns *4—9, 4-10, 4-11, 4-14, 4-33, A-5 
stop command ¢ 4-14 
subroutines 
argument usage * 4-16 to 4-19 
list * 4-15 
supported device « 4—1 
supporting software * 4-3 
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LPA11-K device (Cont.) 
SYS$CANCEL routine * 4-14 
SYS$GETDVI returns « 4—5 
timeout error * 4-2. 


Magnetic tape 

ACP control function * 1-30, 6-15 

ACP create file operation * 1-26 

available function * 6-27 

BOT marker « 6-19, 6-20 

byte count 
read * 6-17 
write * 6-19 

data check * 6-8, 6-17, 6-18 

data security erase function * 6-27 

density * 6-26 

device characteristics »6—-11 to 6-12 

driver * 6-1 

end-of-volume detection » 6-20 

EOF status * 6-17 

EOT 
marker «6-20 to 6-21 
status 6-17, 6-19, 6-21 

error recovery * 6-9 

extended characteristics » 6—12 

features ¢ 6-6 

file attributes » 6-9 

function codes * 6-13, A-6 

function modifiers 
l\O$M_DATACHECK * 6-8, 6-17, 6-18 
IO$M_ERASE « 6-18 
lIO$SM_INHEXTGAP « 6-10 
1O$M_INHRETRY + 6-9 
lIOSM_NOWAIT + 6-19, 6—21, 6-22 
1O$M_REVERSE ¢ 6-17 

/O functions * 6-13 
See also ACP-QIO interface 
arguments * 6-15 
lO$_ACCESS « 6-13 
l\O$_ACPCONTROL « 1-31, 6—15 
lO$_AVAILABLE « 6-27 
1IO$_CREATE ¢ 6-13 
1O$_DEACCESS »* 6-13 
1IO$_DSE ¢ 6-13, 6-27 
1IO$_FLUSH « 6-13 
lIO$_MODIFY ¢ 6-13 
1O$_PACKACK ¢ 6-27 
1O$_READLBLK * 6-17 
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Magnetic tape 

I/O functions (Cont.) 
lO$_READPBLK « 6-17 
1O$_READVBLK « 6-17 
1IO$_ REWIND « 6-19 
lO$_REWINDOFF « 6-21 
lO$_SENSEMODE ° 6-22 
1O$_SETCHAR + 6-23 
lO$_SETMODE « 6-23 
lO$_SKIPFILE * 6-19 
1O$_SKIPRECORD + 6-20 
l1O$_UNLOAD * 6-22 
lO$_WRITELBLK « 6-18 
lO$_WRITEOF + 6-21 
1O$_WRITEPBLK + 6-18 
lO$_WRITEVBLK « 6-18 

/O status block * 6-28 

master adapters * 6-8 

pack acknowledge function * 6-27 

parity * 6-26 

positioning * 1-31 

programming example * 6-28 

quotas * 6-13 

read function * 6-17 

read reverse function * 6-17, 6-18 

rewind function * 6-19 

rewind offline function * 6-21 

sense mode function * 6-22 

set characteristics function »* 6-23 

set mode function * 6-23 
characteristics * 6-25 

skip file function * 6-19 

skip record function * 6-20 

slave formatter » 6-8 

status returns * A—7 

streaming tape systems * 6-10 

supported devices * 6—1 

SYS$GETDVI returns * 6-11 

tape controllers * 6-3 

tape mark * 6-17, 6-20 

thrashing * 6-10 

TMSCP magnetic tapes + 6—1 

TU58 magnetic tape 
See Disk, TU58 

unload function * 6-22 

write end-of-file function * 6-21 

write function * 6-18 

Mailbox 

See also Terminal 

creating * 7-1 

deleting * 7-2 


Mailbox (Cont.) 
device characteristics * 7-4 
disable terminal * 8-21 
driver * 7-1 
function codes « 7-5, A—7 
function modifiers 
IO$M_NORSWAIT « 7-7 
IO$M_NOW ° 7-2, 7-6, 7-7, 7-9, 7-10 
IO$SM_READATTN ¢ 7-9 
IO$M_SETPROT » 7-11 
I/O functions 
lIO$_READLBLK ¢ 7—5 
lIO$_READPBLK « 7-5 
1O$_READVBLK « 7-5 
1O$_WRITELBLK * 7-6 
1O0$_WRITEOF « 7-9 
1O$_WRITEPBLK ¢ 7-6 
10$_WRITEVBLK ¢ 7-6 
/O status block « 7-12 
list of operations * 7—1 
message format * 7-3 
terminal * 8-18 
message size * 7-2 
multiport memory * 7—1 
permanent 7-2, 7-3, 7-4 
programming example « 7-14 
protection * 7-2, 7-4, 7—11 
read attention AST function « 7-9 
read function «7-5 
set attention AST function * 7-9 
set protection function * 7-11 
status returns * A—-7 
SYS$GETDVI returns » 7—4 
temporary * 7—2, 7-4 
terminal/mailbox interaction * 8—17 
volume protection * 7-11 
write attention AST function * 7-9 
write end-of-file message function * 7-9 
write function * 7-6 
Master adapter * 6-8 
Message format 
See Mailbox 
Mode card 
026 punch mode « 2-2 
029 punch mode « 2-2 
Modify file function *« 1-28 
MOUNT command ¢ 6-27 
Mount function * 1-30 
Multinational character set 
See DEC Multinational Character Set 


Index 


Multiplexer 


DMB32 device » 8-1 
DMF32 device + 8-1 
DZ11 device « 8-1 
DZ32 device « 8-1 


O 


Out-of-band AST * 8-13, 8-46 


p 


Parity flag * 8—41 
Passall mode « 5-4 
PASSWORD command 

in card reader batch job * 2-2 
Pasthru mode « 8-9, 8-11, 8-24, 8-27 
Permanent mailbox 

See Mailbox 
Port access mode « 3-12 
Port selection * 3-12 
Printer 

See Line printer 
Protection 

See also Mailbox 

directory entry « 1-9 
Pseudoterminal 

canceling request * 9-2 

control connection routines »* C—1 

creating * 9-1 

deleting * 9~2 

device characteristics * 9-3 

driver * 9-1 

event notification * 9-6 

features * 9-3 

flow control * 9-6 

1/O buffers * 9-4 

programming example * 9-8 

reading data + 9-5 

using write with echo «9-5 

writing data « 9-5 
PTD$CANCEL control connection routine » C-2 
PTD$CREATE control connection routine * C-3 
PTD$DELETE control connection routine » C-6 
PTD$READ control connection routine * C—7 
PTD$SET_EVENT_NOTIFICATION control 

connection routine » C-9 

PTD$WRITE control connection routine * C—12 
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Quota 
AST * 3-24, 4-14, 6-13, 7-5, 7-9, 8-43 
buffered I/O * 3-24, 6-13, 7-5 
BYTELIM ¢ 1-11 
direct I/O * 3-24, 6-13 
disk * 1-33 to 1-34 
mailbox buffer * 7-2, 7-3, 7-5 

Quota file transfer block * 1-33 


R 


RA6O disk + 3-5 

RA70 disk « 3-5 

RAS0O disk « 3-5 

RBO2 disk * 3-6 

RC25 disk * 3-6 

RD53 disk * 3-6 

RD54 disk « 3-6 

Read attention AST function « 7-9 

Read/write attributes subfunction * 1-14 

Record attributes value * 1-20 

RETURN key « 8-6 

Rewind offline function * 6-21 

RF30 disk * 3-7 

RF71 disk * 3—7 

RKO6 cartridge disk * 3-7 

RKO7 cartridge disk * 3-7 

RMO3 disk * 3-7 

RMO5 disk ¢ 3-7 

RP0O5 disk * 3-7 

RP06 disk « 3-7 

RP07 disk * 3-7 

RQDXS3 disk controller * 3-5 

RSX-11M/M-—PLUS 
differences from VMS « 4-35 

RTPAD + 8-11 

RX01 console disk « 3-8 

RX02 Diskette * 3-8 

RX23 diskette * 3-9 

RX33 diskette * 3-10 

RX50 diskette » 3-10 

RX-series * 3-9 

RZ22 disk * 3-10 

RZ23 disk * 3-10 

RZ55 disk * 3-10 
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SCSI 
disk 
class driver * 3-22 
error recovery * 3-17, 3-22 
SCSI Class driver « 11-2 
SCSI class/port architecture * 11-2 
SCSI command 
disabling retry * 11-8 
enabling retry * 11-13 
padding, when required * 11-14 
setting disconnect timeout for « 11-8, 11-14 
setting DMA timeout for * 11-8, 11-14 
setting phase change timeout for + 11-8, 11-14 
SCSI disconnect feature 
enabling * 11—7 
SCSI port driver * 11-2 
SCSI_NOAUTO system parameter * 11-10 
Secior translation * 3—18 
Seek operation * 3-16 
Sense tape mode function * 6-22 
Serial line multiplexer « 8—1 
Set attention AST 
See Attention AST 
SET CARD_READER command ¢ 2-2 
Set characteristic 
card reader * 2-7 
line printer « 5-9 
magnetic tape * 6-23 
terminal * 8-38 
SET HOST facility « 8—11 
Set mode 
card reader * 2-7 
line printer * 5-9 
magnetic tape * 6-23 
mailbox * 7-9 
terminal * 8-38 
SET TERMINAL command « 8-4, 8-19, 8-25 
Set translation mode * 2-2 
Shadow set virtual unit driver * 10-1 
functions * 10-4 
hardware configurations * 10—2 
system configuration * 10-2 
SHDRIVER.EXE « 10-1 
Sil integral adapter * 3-4 
Skip file function * 6—20 
Skip sectoring * 3-17 
Slave formatter * 6-8 


Small Computer System Interface (SCSI) 


See SCSI 

SS$_ABORT return « 8-45, 8-50, A-2, A-3, A-5, 

A-7, A-9 
SS$_ACCONFLICT return * A—1 
SS$_ACCVIO return * 7-12, 8-51 
SS$_ACPVAFUL return » A-1 
SS$_BADATTRIB return * A—1 
SS$_BADCHKSUM return + A-1 
SS$_BADESCAPE return » 8-7, A-9 
SS$_BADFILEHDR return + A—1 
SS$_BADFILENAME return + A-1 
SS$_BADFILEVER return « A—1 
SS$_BADIRECTORY return * A-1 
SS$_BADPARAM return « 8—51, A-1, A-5, A-9 
SS$_BADQFILE return * A—1 
SS$_BLOCKCNTERR return « A—1 
SS$_BUFFEROVF return * 7-6, A-7 
SS$_BUFNOTALIGN return * A-5 
SS$ CANCEL return * A~3, A-5, A-7, A-9 
SS$_CONTROLC return » 8-46, A-9 
SS$_CONTROLO return + A-9 
SS$_CONTROLY return » A-9 
SS$_CREATED return « A—1 
SS$_CTRLERR return * A-3, A-5, A-7 
SS$_DATACHECK return * A-3, A-5, A-7 
SS$_DATAOVERUN return * 8-9, A-2, A-3, A-7, 

A-9 
SS$_DEVACTIVE return * 8-50, A-5 
SS$_DEVCMDERR return + A-5 
SS$_DEVICEFULL return « A—1 
SS$_DEVOFFLINE return * A—7 
SS$_DEVREQERR return « A-5 
SS$_DIRFULL return + A—1 
SS$_DIRNOTEMPTY return * A—1 
SS$_DRVERR returns A-3, A-7 | 
SS$_DUPDSKQUOTA return * A—1 
SS$_DUPFILENAME return « A—1 
SS$_ENDOFFILE return » 6-21, 7-6, 7-9, A-1, A-2, 

A-7 
SS$_ENDOFTAPE return * A—7 
SS$_ENDOFVOLUME return ¢ 6-21, A-7 
SS$_EXBYTLM return * A—1 
SS$_EXDISKQUOTA return * A—1 
SS$_EXQUOTA return * A-5 
SS$_FCPREADERR return * A—1 
SS$_FCPREWNDERR return * A-1 
SS$_FCPSPACERR return « A-1 
SS$_FCPWRITERR return » A—1 
SS$_FILELOCKED return « A—1 
SS$_FILENUMCHK return * A—1 
SS$_FILEPURGED return » A—1 
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SS$_FILESEQCHK return ¢ A—1 
SS$_FILESTRUCT return + A—1 
SS$_FILNOTEXP return * A—1 
SS$_FORCEDERR return « A-3 
SS$_FORMAT return * A~3, A-7 
SS$_HANGUP return * 8-13 
SS$_HEADERFULL return « A—1 
SS$_IBCERROR return « A—1 
SS$_IDXFILEFULL return »* A-1 
SS$_ILLCNTRFUNC return * A—1 
SS$_ILLIOFUNC return * 8-50, A-3, A-7 
SS$_INCOMPAT return « A-9 
SS$_INSFBUFDP return * A-5 
SS$_INSFMAPREO return « A-5 
SS$_INSFMEM return * 7—-12, A-5 
SS$_IVADDR return « A-3 
SS$_IVBUFLEN return « A-3, A-5 
SS$_IVMODE return « A-5 
SS$_MBFULL return « 7-2, 7-7, 7-12 
SS$_MBTOOSML return * 7-12 
SS$_MCNOTVALID return » A-5 
SS$_MEDOFL return * A-3, A-7 
SS$_NODISKQUOTA return + A—1 
SS$_NOMOREFILES return * A—1 
SS$_NONEXDRYV return * A-3, A-7 
SS$_NOPRIV return * 7-12, 8-51, A-1 
SS$_NOQFILE return * A-1 
SS$_NORMAL return * 8-50, 8-51, A-2, A-3, A-7, 
A-9 
SS$_NOSUCHFILE return * A-1 
SS$_NOTAPEOP return « A-2 
SS$ _NOTLABELMT return « A-2 
SS$_NOTPRINTED return « A-2 
SS$_NOTVOLSET return + A-2 
SS$_OPINCOMPL return * A-3, A—7 
SS$_OVRDSKQUOTA return « A-2 
SS$_PARITY return» A-3, A-5, A-7, A-9 
SS$_PARTESCAPE return + 8-7, 8-30, A-9 
SS$_POWERFAIL return * A-5 
SS$_QFACTIVE return » A~2 
SS$_QFNOTACT return * A-2 
SS$_RCT return * A-3 
SS$_RDDELDATA return « A-3 
SS$_SERIOUSEXCP return * A-2, A-7 
SS$_SUPERSEDE return « A-2 
SS$_TAPEPOSLOST return * A-2 
SS$_TIMEOUT return « 8-27, 8-50, A-3, A-5, A-7, 
A-9: 
SS$_TOOMANYVER return « A-2 
SS$_UNSAFE return * A-3, A-7 
SS$_VOLINV return * A-3, A-7 
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SS$_WASECC return « A-3 
SS$_WRITLCK return « A-2, A-3, A-7 
SS$_WRONGACP return » A-2 
Standard Disk Interconnect (SDI) * 3-5 
Synchronous SCSI data transfer mode 

enabling * 11-7, 11-13 
SYS$ASSIGN routine « 7-2, 8-17, 8-52 
SYS$CANCEL routine » 4-14 
SYS$CREMBx routine * 7—1 
SYS$DASSGN routine + 7-2 
SYS$DELMBX routine * 7-3 
SYS$DISMOUNT routine * 1-32 
SYS$GETDVI 

SCSI generic class driver * 11-14 
SYS$GETDVI routine * 6-11 

card reader * 2-5 

disk * 3-22 

line printer * 5-3 

LPA11-K device * 4—5 

mailbox * 7—4 

terminal * 8-20 
SYS$QIO 

format for request to SCS! generic class driver « 

11-11 

System console terminal « 8—1 
System Generation Utility (SYSGEN) 

configuring SCSI devices « 11-9 


7 


Tab 
CTRL/I + 8-6 
terminal mechanical * 8-21 
terminal tab stops * 8-35 
Tape 
See Magnetic tape 
Tape class driver 
disabling the loading of * 11-10 
Tape mark * 6-17, 6-20 
Temporary mailbox » 7—4 
Terminal 
ANSI CRT terminal » 8-22 
autobaud detection * 8-19, 8-22 
baud rate «8-19, 8-22, 8-40 
bell (CTRL/G) * 8-9 
broadcast message * 8-18, 8-21, 8-23, 8-46 
carriage control * 8-36 
characteristic 
See Terminal characteristic 
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command line editing » 8-3, 8-34 

command recall (CTRL/B) « 8-3, 8-6 

control and data signals » 8-16 

control characters «8-4 to 8-6, 8-9, 8-27 
numeric values * B—1 

control sequences « 8-8 

cursor movement * 8-3, 8-5, 8-22 

delete character * 8-3 

delete line (CTRL/U) * 8-5, 8-27 

device characteristics » 8-20 
categories * 8-25 
changing * 8-42 
extended * 8-22 

dial-up 
characteristic » 8-22 
lines * 8-13, 8-23, 8-42 
support * 8-13 

DIGITAL CRT terminal « 8-23 

discard output (CTRL/O) « 8-5, 8-27, 8-35 

driver ¢ 8—1 

duplex modes « 8-10, 8-13 

enable CTRL/C AST + 8-42 

enable CTRL/Y AST + 8-42 

escape sequences « 8-7, 8-57 
ANSI + B-9 
Digital-private « B—9 
overflow size (item code) * 8-30 

extended characteristics *« 8-22 

fallback conversion * 8-11, 8-24, 8-42 

features * 8-2 

form feed * 8-21, 8-35 

frame size * 8-41 

function codes « 8-26, A-8 

function modifiers 
See also Terminal, item codes 
lIO$M_BRDCST + 8-46, 8-55 
IO$M_BREAKTHRU « 8-10, 8-35 
IO$M_CANCTRLO ¢ 8-5, 8-35 
IO$M_CTRLCAST « 8-42 
IO$SM_CTRLYAST ¢ 8-5, 8-13, 8-42 
IO$SM_CVTLOW « 8-27 
lO$M_DSABLMBxX « 8-27 
lO$M_ENABLMBxX « 8-35 
IO$SM_ESCAPE ¢ 8-7, 8-27 
IO$M_EXTEND « 8-27, 8-29 
lIO$M_HANGUP « 8-42 
JO$M_INCLUDE « 8-19, 8-43, 8-46 
IO$M_LOOP * 8-45 
IO$M_LT_CONNECT »* 8-49 
IO$M_LT_DISCON « 8-49 


Terminal 

function modifiers (Cont.) 

IO$M_LT_MAP_PORT + 8-49 
P1 parameters * 8-50 

IO$M_LT_RATING « 8-49 
IO$M_MAINT « 8-44, 8-45 
IO$M_NOECHO ¢ 8-9, 8-10, 8-24, 8-27 
IO$M_NOFILTR « 8-27 
IO$M_NOFORMAT « 8-11, 8-35, 8-45 
IO$M_OUTBAND « 8-46 
IO$M_PURGE ° 8-27 
IO$M_RD_MODEM « 8-54 
IO$M_REFRESH « 8-36 
lIO$M_SET_MODEM « 8-44 
IO$M_TIMED « 8-27 
lIO$M_TRMNOECHO ¢ 8-28 
IO$M_TT_ABORT « 8-19, 8-46 
IO$M_TYPEAHDCNT ° 8-54 
IO$M_UNLOOP « 8-45 

hang up * 8-13, 8-17, 8-18, 8-23, 8-24, 8-42, 
8-52 

/O functions 
CTDRIVER « 8-35 
l1O$_READLBLK + 8-26 
1\O$_READPROMPT ¢ 8-26, 8-27 
1O$_READVBLK + 8-26 
l1O$_SENSECHAR « 8-53 
1O$_SENSEMODE « 8-53 
1IO$_SETCHAR « 8-38 
lO$_SETMODE « 8-38 
1O$_TTY_PORT * 8-49 
10$_WRITELBLK « 8-34 
lIO$_WRITEPBLK + 8-34 
lO$_WRITEVBLK « 8-34 

I/O status block * 8-56 

initiate login « 8-9 

input processing * 8-3 

insert/overstrike (CTRL/A) * 8-3, 8-6 

interrupt (CTRL/Y) « 8-5 

item codes «8-30 to 8-33 

itemlist read * 8-29 
example * 8-70 
item codes * 8-30 to 8-33 
item descriptor * 8-30 

LAT line * 8-1 

LAT port driver * 8-48 
application services creation « 8-51 
example * 8—74 
I/O functions * 8-49 

LAT rejection codes « 8-58 

line editing «8-3, 8-23 
See also Terminal, item codes 
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line feed « 8—35 
line terminators * 8-9 
mailbox * 8—17, 8-35 
message format + 8-18 
message types ¢ 8-18 
modem 
characteristic * 8-21 
control signals « 8-16 
data signals * 8-16 
protocol « 8-14 
sense signals * 8-54 
signal control * 8-13 
no type-ahead » 8-21 
out-of-band 
See also Out-of-band AST 
characters * 8-19 
output 
CTDRIVER « 8-11 
RTPAD * 8-11 
SET HOST « 8-11 
output formatting «8-11, 8-25 
output processing * 8-10 
page length and width » 8-40, 8-53 
parity flag « 8-41 
pasthru mode « 8-9, 8—11, 8-24, 8-27 
process preservation * 8-17 
programming examples * 8-59 
protocol « 8-14 
read function * 8-26 
arguments * 8-26 
function modifiers * 8-27 
itemlist read * 8-29 
terminating * 8-26 
terminators * 8~28 
with timeout * 8-26, 8-27 
read verify * 8-6, 8-33 
example * 8—70 
receive speed « 8-40 
redisplay data (CTRL/R) * 8-6, 8-27 
ReGIsS graphics » 8-24 
restart data (CTRL/Q) * 8-6 
sense characteristics function * 8-53 
sense mode function « 8-53 
serial line multiplexer » 8—1 
set characteristics function * 8-38 
arguments * 8-39 
set mode function * 8-38 
arguments * 8-39 
SET TERMINAL DCL command « 8-4, 8-19, 8-25 
SIXEL graphics * 8-24 
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Terminal (Cont.) 
special operating modes * 8-10 
status (CTRL/T) * 8-6 
status returns * A-9 
stop data (CTRL/S) + 8-6 
supported devices * 8—1 
SYS$GETDVI returns * 8-20 
system password ¢ 8-24 
tab 
CTRL/I + 8-6 
mechanical * 8-21 
stops * 8-35 
terminator mask * 8-28, 8-29 
time (CTRL/T) * 8-6 
transmit speed * 8—40 
TTY_DIALTYPE SYSGEN parameter * 8-13, 8-14, 
8-16 
type-ahead * 8-8, 8-17, 8-21, 8-54 
alternate buffer » 8-22 
unsolicited data * 8-17 
write breakthrough function » 8-36 
write function * 8—34 
carriage control * 8-36 
function modifiers * 8-35 
XON/XOFF control * 8-24 
Terminal characteristic 
ANSI CRT ¢ 8-22 
ASCIl (8-bit) code » 8-21 
baud rate * 8-22 
block mode « 8-23 
dial-up line * 8-23 
dial-up terminal » 8-22 
DIGITAL CRT « 8-23 
DMA mode * 8—23 
edit * 8-23 
extended characteristics * 8-22 
local echo * 8-24 
modem « 8-21 
modify hang up « 8-24 
no echo « 8-21 
no type ahead « 8-21 
pasthru mode * 8-24 
ReGIS graphics « 8-24 
remote terminal * 8-22 
secure * 8—24 
set speed * 8-24 
SIXEL graphics * 8—24 
system password * 8-24 
XON/XOFF * 8-24 
Terminator character bit mask * 8-28 
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Thrashing 

magnetic tape * 6-10 
Timeout 

for SCSI device * 11-8, 11-14 
Translation 

logical to physical «3-18 
Translation mode card 

026 punch mode « 2-2 

029 punch mode « 2-2 
Truncate subfunction * 1-13 
TU58 magnetic tape 

See Disk 
Type-ahead 

See Terminal, type-ahead 


U 


UDAS5O disk adapter « 3-3 
Unload function 

disk ¢ 3-32 

magnetic tape * 6-22 


W 


Write attention AST function * 7-9 
Write breakthrough function * 8—36 
Write end-of-file function 

magnetic tape * 6-21 

message * 7-9 
Write protection 

hardware « 10-4 


X 


XQP (extended QIO processor) 1-1 
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